Firebase 배포 제외 파일 설정: firebase.json의 ignore 사용법

학습 목표와 사전 지식

목표: Hosting과 Functions ignore의 기준 디렉터리를 구분하고 필요한 런타임 파일을 보존합니다.
사전 지식: firebase.json, 빌드 산출물, 상대 경로

Firebase 배포 제외는 해당 제품의 firebase.json 설정에서 관리합니다. Hosting의 public과 Functions의 source가 다르므로 같은 glob을 복사해도 제외 대상이 같지 않습니다. 제외 설정은 이미 공개된 비밀값을 회수하지 못합니다.

설정	기준	반드시 남길 것
hosting.public: out	배포할 정적 산출물 out	index.html·실제 참조 자원
functions.source: functions	서버 코드 functions	package.json·실행 진입점·빌드 결과

firebase.json · 전체 최소 설정 예시; 기존 rewrites·headers·다중 사이트 설정은 병합

{
  "hosting": {
    "public": "out",
    "ignore": [
      "firebase.json",
      "**/.*",
      "**/node_modules/**",
      "**/*.map",
      "**/*.test.*"
    ]
  },
  "functions": [
    {
      "source": "functions",
      "codebase": "default",
      "ignore": [
        "node_modules",
        ".git",
        "firebase-debug.log",
        "firebase-debug.*.log",
        "*.local",
        "coverage/**",
        "**/*.test.*",
        "serviceAccountKey.json"
      ]
    }
  ]
}

왜 node_modules를 제외해도 되는가

Functions 배포는 package.json 의존성 설치 과정을 사용합니다. 로컬 node_modules와 테스트 결과를 업로드할 이유는 없습니다. 반대로 TypeScript 프로젝트가 package.json의 main으로 lib/index.js를 가리킨다면 빌드된 lib를 제외하면 실행 코드가 사라집니다. 의존성을 devDependencies로만 옮겨 런타임에서 찾지 못하는 문제도 ignore와 별도로 확인하세요.

Next.js를 out으로 배포하는 조건

이 설정은 정적 내보내기 산출물 out이 있는 경우입니다. SSR·서버 기능이 필요한 Next.js 앱을 out Hosting만으로 서비스할 수 있다는 뜻이 아닙니다. 빌드가 실제로 out/index.html과 참조 자원을 만들었는지 먼저 확인하세요. 소스맵 제외는 디버깅 가시성을 바꾸는 선택이며 파일명에 비밀을 숨기는 보안 장치가 아닙니다.

작게 확인하는 배포 점검

변경 전 firebase.json을 버전 관리에 저장하고 out의 실제 파일 목록과 HTML/CSS의 참조를 비교합니다. 개발용 Hosting preview에 배포한 뒤 정상 경로·없는 경로·CSS·이미지·깊은 URL을 검사합니다. Functions는 먼저 빌드하고 진입점이 존재하는지 확인합니다. ignore 추가 후 앱이 동작하지 않으면 배포 로그의 누락 파일과 glob 범위를 우선 대조합니다.

제외와 비밀 회수는 다른 작업

서비스 계정 키는 Secret Manager나 신뢰 서버의 기본 자격 증명을 사용합니다. 이미 저장소나 배포물에 노출한 키가 있다면 ignore 추가만으로 해결되지 않으며 별도 회수가 필요합니다. 웹 Firebase config는 클라이언트용 설정이고 서비스 계정 키와 같은 비밀 종류가 아닙니다.

직접 확인할 결과

JSON 파싱
main 경로·빌드 산출물 존재 확인 절차
개발 preview 자원 응답 확인 절차

검증 범위와 기준일

공식 문서 확인일: 2026-09-13. 웹 SDK 예제는 모듈형 API 기준입니다. 이 글의 코드·구조 정적 검토와 실제 클라우드 인증·저장·배포 검증을 구분합니다. 본인 개발 Firebase 프로젝트의 실제 인증·권한·배포 요청은 이 편집 환경에서 실행하지 않았습니다.

이어서 학습하기

• Firestore seed data 설계: 리뷰 더미 데이터 구조 잡기
• Firebase Firestore 인덱스 삭제 질문 해결: 배포 중 안전하게 판단하기

공식 문서

• https://firebase.google.com/docs/hosting/full-config
• https://firebase.google.com/docs/functions/manage-functions
• https://firebase.google.com/docs/projects/api-keys