Firebase에서 .firebaseignore 깔끔하게 작성 하는 방법

• .firebaseignore란 무엇인가
• Firebase 배포 구조와 ignore 동작 방식
• 실무에서 사용하는 ignore 예시
• 프로젝트 공용으로 사용 가능한 기준

.firebaseignore란 무엇인가

.firebaseignore는 Firebase CLI가 deploy 명령을 실행할 때 업로드 대상에서 제외할 파일과 폴더를 정의하는 설정 파일입니다.
Git의 .gitignore와 역할은 유사하지만, 적용 대상은 “버전 관리”가 아니라 “Firebase 배포”입니다.

이 파일이 존재하면 Firebase CLI는 프로젝트 루트 기준으로 파일을 검사하며,
ignore 규칙에 해당하는 항목은 Hosting, Functions, Storage 등 어떤 서비스에도 업로드하지 않습니다.

Firebase 배포 구조와 ignore 동작 방식

Firebase는 firebase.json에 정의된 각 서비스 기준으로 파일을 수집합니다.
이 과정에서 .firebaseignore가 함께 적용되어, 최종 업로드 대상이 결정됩니다.

firebase.json
.firebaseignore
functions/
public/
.next/
node_modules/

예를 들어 Hosting 배포 시에는 public 또는 out 폴더가 기준이 되지만,
ignore 규칙에 포함된 파일은 해당 경로 내부에 있더라도 업로드되지 않습니다.

실무에서 사용하는 ignore 예시

아래 예시는 Next.js 기반 프로젝트에서 Firebase Hosting과 Functions를 함께 사용하는 경우를 기준으로,
실무에서 가장 많이 사용되는 패턴을 정리한 .firebaseignore 예시입니다.

# Dependencies & builds
node_modules/
.next/
out/
dist/
*.tsbuildinfo

# Secrets
.env*
serviceAccountKey.json
firebase-adminsdk*.json

# Tests
__tests__/
*.test.*
*.spec.*
coverage/
jest.config.*
jest.setup.*

# IDE / OS
.idea/
.vscode/
.DS_Store
Thumbs.db

# Firebase local
.firebase/
*-debug.log

# Misc
*.log
*.local

이 구성은 “빌드 산출물”, “비밀 정보”, “테스트 코드”, “로컬 개발 환경 파일”을 명확히 분리하여
배포 대상에 포함되지 않도록 하는 것을 목적로 합니다.
특히 .env*와 Firebase Admin SDK 키 파일은
클라이언트나 서버 배포에 포함될 경우 즉시 보안 사고로 이어질 수 있으므로 반드시 제외해야 합니다.

또한 Jest 테스트 파일과 커버리지 결과는 실행 환경에서는 필요하지 않기 때문에,
CI나 로컬 테스트 단계까지만 사용하고 Firebase 배포 대상에서는 제거하는 것이 일반적인 운영 방식입니다.

내 프로젝트에 적용할 때 유의할 점

위 예시는 범용적으로 사용하기 좋은 기준이지만,
실제 프로젝트에 그대로 적용할 경우 반드시 한 번 더 점검해야 할 항목들이 있습니다.
특히 Hosting과 Functions를 함께 사용하는 구조에서는 “무조건 제외”가 아니라
“어디에서 필요한 파일인지”를 기준으로 판단해야 합니다.

① Hosting 기준 빌드 결과물 확인
Next.js 프로젝트에서는 out/, public/ 등
Hosting에서 실제로 서비스할 디렉토리가 무엇인지 먼저 확정해야 합니다.
빌드 결과가 들어가는 폴더를 ignore 해버리면 정상 배포가 되지 않으므로,
firebase.json의 Hosting 설정과 항상 함께 검토해야 합니다.

② Functions 배포에 필요한 파일 구분
Functions에서 사용하는 코드와 설정 파일은
Hosting 기준으로는 불필요해 보여도 서버 실행에는 반드시 필요할 수 있습니다.
이 경우 Functions 디렉토리 내부에만 존재하도록 구조를 분리하고,
루트 기준 .firebaseignore 규칙이 Functions 코드까지 막지 않는지 확인해야 합니다.

③ 환경 변수 관리 방식 점검
.env*를 ignore 하는 것은 기본이지만,
실제 운영 환경에서는 Firebase 환경 변수나 Secret Manager를 사용해
서버 실행 시 필요한 값이 정상적으로 주입되는지 반드시 확인해야 합니다.
단순히 파일을 제외하는 것만으로는 설정이 완료되지 않습니다.

④ 테스트 코드 제외 범위 조절
모든 테스트 파일을 제외하는 것이 항상 정답은 아닙니다.
배포 이후에도 실행되는 검증 스크립트가 있다면,
해당 파일은 ignore 대상에서 분리해 관리하는 것이 더 안전합니다.

프로젝트 공용으로 사용 가능한 기준

실무 기준에서 .firebaseignore는 매 프로젝트마다 새로 고민하기보다는,
자주 빠지지 않고 들어가는 항목들을 공용 템플릿으로 관리하는 방식이 효율적입니다.
아래 항목들은 프레임워크나 서비스 종류와 무관하게,
대부분의 Firebase 프로젝트에서 배포 대상에 포함되지 않는 파일들입니다.

분류	제외 대상 예시
빌드 산출물	dist/, build/, out/
캐시	.cache/, .turbo/, .parcel-cache/
로그	logs/, *.log
테스트	__tests__/, coverage/, *.test.*
IDE 설정	.vscode/, .idea/
OS 파일	.DS_Store, Thumbs.db
문서	docs/, *.md
스크립트	scripts/, tools/
임시 파일	tmp/, temp/
백업	*.bak, *.old

특히 보안과 직접적으로 연결되는 파일들은 별도의 기준으로 관리하는 것이 권장됩니다.
환경 변수나 인증 키 관련 파일은 실수로 배포될 경우 즉시 보안 사고로 이어질 수 있으므로,
프로젝트 초기에 공용 ignore 규칙에 포함시키는 것이 안전합니다.

보안 분류	제외 대상 예시
환경 변수	.env.*, .runtimeconfig.json
인증 키	*.pem, *.key, *.p12
Firebase 설정	.firebaserc, firebase-debug.log

이처럼 .firebaseignore는 특정 프로젝트에 종속된 설정이 아니라,
프레임워크(Next.js, React 등)와 배포 방식(Firebase Hosting, Functions)이 유사하다면
공용 템플릿으로 만들어 재사용하는 것이 유지보수 측면에서 효율적입니다.
이후 프로젝트별 특수한 요구 사항만 추가하거나 제거하는 방식이 가장 안정적인 운영 전략입니다.

정리하면, 공용 .firebaseignore의 판단 기준은 다음 세 가지로 압축할 수 있습니다.
• 배포 대상이 아닌 것
• 언제든 재생성 가능한 것
• 보안에 민감한 것

FAQ

Q. .firebaseignore가 없으면 어떻게 되나요?
Firebase CLI는 기본 규칙만 적용하므로, 빌드 결과물이나 테스트 파일처럼 배포에 필요 없는 항목까지 함께 업로드될 수 있습니다.
이 경우 Hosting 저장 용량이나 Functions 배포 용량이 불필요하게 증가할 수 있으며,
사용량이 누적되면 스토리지·트래픽·빌드 리소스 기준으로 비용이 청구될 가능성도 생깁니다.
따라서 실제 운영 환경에서는 반드시 .firebaseignore를 통해 배포 범위를 명확히 관리하는 것이 중요합니다.

Q. 배포 후 이전 파일은 자동으로 삭제되나요?
결론부터 정리하면, Firebase Hosting 기준에서는 자동으로 정리됩니다.

Firebase Hosting은 파일을 하나씩 추가·수정하는 방식이 아니라,
배포 시점마다 “현재 결과물 전체를 하나의 스냅샷으로 교체”하는 구조로 동작합니다.

즉, 이번 배포 결과에 포함되지 않은 파일은
.firebaseignore 때문이든, 빌드 결과에서 빠졌든 관계없이
자동으로 서비스 대상에서 제거됩니다.

예를 들어 이전 배포에 존재하던 파일이 이번 배포 결과에 없으면,
해당 파일은 Hosting에서 더 이상 제공되지 않습니다.

정확한 역할 구분
.firebaseignore는 “이미 배포된 파일을 남길지 말지”를 결정하는 설정이 아니라,
이번 배포 버전에 어떤 파일을 포함할지 결정하는 역할을 합니다.

단, 이 동작 방식은 Firebase Hosting에 한정되며,
Firestore 데이터나 Storage 파일, 로컬 Emulator 파일 등은
배포 과정에서 자동으로 삭제되지 않습니다.

Q. .gitignore와 함께 사용해도 되나요?
역할이 다르므로 함께 사용하는 것이 일반적이며, 서로 영향을 주지는 않습니다.