중급Firebase Hosting으로 웹사이트 배포하기

어떤 웹사이트에 맞나요?

이 장은 HTML·CSS·JavaScript로 빌드되는 정적 웹사이트를 Firebase Hosting에 올리는 과정입니다. 브라우저에서 외부 API를 호출하는 정적 앱도 배포할 수 있지만, 빌드 폴더를 올리는 것만으로 서버 API나 SSR이 실행되지는 않습니다. Next.js 서버 기능이 필요하면 App Hosting 배포를 읽으세요.

준비하기

연습용 Firebase 프로젝트와 CLI를 준비합니다. 아래 명령의 PROJECT_ID는 콘솔에 표시되는 프로젝트 ID로 바꿉니다. 표시용 프로젝트 이름과 혼동하지 마세요. 명령은 웹 프로젝트 루트에서 실행합니다.

npm install -g firebase-tools
firebase login
firebase projects:list
npm run build
firebase init hosting

초기화에서 기존 프로젝트를 선택하고 공개 폴더를 실제 빌드 결과로 지정합니다. 예를 들어 Vite는 보통 dist, Next.js 정적 내보내기는 out이지만 프로젝트 설정을 직접 확인해야 합니다. 기존 firebase.json이 있으면 덮어쓰기 전에 변경 내용을 살펴보세요. Hosting 시작하기 ↗

라우팅과 공개 파일 설정

SPA의 클라이언트 라우터는 새로고침할 때 index.html로 연결하는 설정이 필요할 수 있습니다. 모든 프로젝트에 SPA 옵션을 켜지 말고 실제 라우팅 방식에 맞춥니다. API 오류까지 index.html로 돌려 JSON 파싱 실패를 숨기지 않도록 주의하세요.

Vite SPA 예시입니다. 기존 설정 전체를 지우는 대신 hosting 항목에 필요한 값만 적용합니다.

{
  "hosting": {
    "public": "dist",
    "ignore": ["firebase.json", "**/.*", "**/node_modules/**"],
    "rewrites": [{ "source": "**", "destination": "/index.html" }]
  }
}

미리보기 후 배포

firebase hosting:channel:deploy preview --project PROJECT_ID

발급된 미리보기 주소에서 첫 화면과 하위 경로 직접 접속, 이미지, 로그인·API 요청을 확인합니다. 정적 파일이 연습용 서버를 호출하는지 확인하고 운영 데이터에 실수로 쓰지 않도록 환경을 구분하세요. 준비가 끝나면 대상을 명시해 Hosting을 배포합니다.

npm run build
firebase deploy --only hosting --project PROJECT_ID

Hosting 배포는 Firestore 규칙·인덱스나 별도 API 서버를 함께 반영하는 명령이 아닙니다. 필요한 다른 배포 항목은 별도로 확인하세요. 빌드 산출물에 비밀키가 포함되지 않았는지도 점검합니다.

자주 발생하는 문제

완료 확인

• 배포 URL에서 하위 페이지 직접 접속을 확인했다.
• 정적 파일과 API의 운영 주소를 구분했다.
• 배포한 프로젝트 ID와 이전 버전 복구 경로를 기록했다.

공식 참고자료

확인 기준일: 2026-10-22.

• Hosting 시작하기 ↗
• 변경 테스트·미리보기·배포 ↗
• 다음: 도메인과 HTTPS 연결