대용량 파일 깃허브에 업로드하기 (feat. Git LFS)

inguk·2025년 3월 5일

안녕하세요! 오늘은 제가 개발하면서 겪은 대용량 파일 관리에 대한 이슈를 공유해보려고 합니다.

🤔 문제 상황

프로젝트를 진행하면서 3D 모델링 파일(.splat)을 깃허브에 올려야 하는 상황이 생겼는데요.
파일 크기가 200MB라서 깃허브에 바로 올리기가 힘들었습니다.

깃허브 업로드 용량 제한사항
무료 플랜: 저장소당 총 용량 제한 100GB
단일 파일 크기 제한: 100MB
Git LFS 사용시 최대 2GB

먼저 Git LFS를 사용했습니다

💡 Git LFS(Large File Storage)란?

Git LFS는 대용량 파일을 효율적으로 관리할 수 있게 해주는 Git 확장 기능입니다.
대용량 파일을 별도의 서버에 저장하고, Git 저장소에는 파일에 대한 참조만 저장합니다.

😅 시도했던 방법들
1. Git LFS 시도

# Git LFS 설치 및 설정
git lfs install
git lfs track "*.splat"
git add .gitattributes
git commit -m "Git LFS 설정 추가"

# 파일 추가 시도
git add public/data/*.splat
git commit -m "대용량 파일 추가"
git push

결과: 실패 😭
기존에 사용중이던 레포지토리라 이전에 lfs를 사용하려다 실패한 이력이 있어서
더 문제를 해결하는데 어려움이 있네요

remote: error: File public/data/model.splat is 202.05 MB; this exceeds GitHub's file size limit of 100.00 MB

💡 해결방법: AWS S3 활용

결국 AWS S3를 사용하기로 했습니다.

aws s3 계정생성 및 버킷 생성
버킷을 로컬과 배포서버에서 불러오기위해선
아래와같이 버킷 CORS 설정과 정책을 설정해줘야됩니다.
1. S3 버킷 CORS설정

[
    {
        "AllowedHeaders": ["*"],
        "AllowedMethods": ["GET"],
        "AllowedOrigins": [
            "http://localhost:3001",
            "https://your-domain.vercel.app"
        ],
        "ExposeHeaders": [],
        "MaxAgeSeconds": 3000
    }
]

S3 버킷 정책설정

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowSpecificOrigins",
            "Effect": "Allow",
            "Principal": "*",
            "Action": "s3:GetObject",
            "Resource": "arn:aws:s3:::your-bucket-name/*",
            "Condition": {
                "StringLike": {
                    "aws:Referer": [
                        "http://localhost:3001/*",
                        "https://your-domain.vercel.app/*"
                    ]
                }
            }
        }
    ]
}

이와같이 설정하니 정상적으로 버킷 스토리지에 있는 파일을 불러올 수 있었습니다

🤔 추가로 발견된 문제

기존 로컬로 파일렌더링시 속도(841ms 49.2MB 기준)

AWS S3로 파일렌더링시 속도(평균 15초 49.2MB 기준)

성능 비교
로컬 vs S3 로딩 속도 비교
로컬 환경: 50MB 파일 렌더링 시간 0.8초
S3 환경: 50MB 파일 다운로드 + 렌더링 시간 평균 15초

이같이 s3로 사용하자니 파일 다운로드시간이 대폭 상승해 사용하기엔 어려움이 발생했습니다.
200mb인 파일도 있기때문에 2분이 넘을것으로 예상해 결국 aws s3도 포기하고 다시한번
git LFS에 도전한결과

각종 캐시문제나 이전 커밋들이 방해가 된다고 판단해 새로운 레포지토리를 생성해
레포지토리 세팅을 마치고 파일을 전부 이전 레포지토리에서 다운받은 후 진행했습니다

Git LFS 설치
git lfs install

추적할 파일 확장자 설정
git lfs track "*.splat"

.gitattributes 파일 커밋
git add .gitattributes
git commit -m "Configure Git LFS"

파일 추가 및 커밋
git add your-large-file.splat
git commit -m "Add large file"
git push origin main

레포지토리를 새로 생성하니 정상적으로 깃허브에 올라간걸 확인할 수 있었습니다