프론트엔드 배포 로드맵: Vercel·Firebase Hosting·App Hosting 선택 기준

• 1단계: 배포 플랫폼 선택
• 2단계: 로컬 빌드 확인
• 3단계: 환경 변수 분리
• 4단계: 미리보기 배포
• 5단계: 운영 도메인·보안
• 6단계: 배포 후 검증
• 프로젝트별 완료 기준

1단계: 렌더링 방식과 운영 범위로 플랫폼을 고릅니다

무료 요금제나 익숙한 로고만 보고 선택하지 말고 정적 파일만 배포하는지, 서버 렌더링과 API가 필요한지, Firebase Auth·Firestore 같은 서비스와 얼마나 밀접한지를 먼저 확인하세요.

Firebase Hosting과 App Hosting은 이름이 비슷하지만 역할이 다릅니다. 정적 배포와 풀스택 프레임워크 배포의 구분은 Firebase Hosting과 App Hosting 차이에서 더 자세히 볼 수 있습니다.

2단계: 배포 전에 로컬 빌드를 통과시킵니다

개발 서버가 열린다고 배포 빌드가 성공하는 것은 아닙니다. CI 환경은 운영 모드로 빌드하며 대소문자 경로, 타입 오류, 누락된 환경 변수, 서버 전용 API 사용 문제가 드러날 수 있습니다. 배포 서비스에 연결하기 전에 프로젝트에서 실제 빌드 명령을 실행하세요.

npm ci
npm run lint
npm run build
npm run start

정적 SPA라면 빌드 결과 폴더에 index.html과 필요한 자산이 생성됐는지 확인합니다. Next.js라면 정적 내보내기인지 서버 런타임이 필요한지 구분하고, 프로젝트가 사용하는 Node.js 버전도 저장소와 배포 설정에서 맞춥니다.

3단계: 환경 변수와 비밀 값을 분리합니다

로컬의 .env 파일을 그대로 커밋하지 않습니다. 브라우저에 포함돼도 되는 공개 설정과 서버에서만 읽어야 하는 비밀 값을 구분하고, 개발·미리보기·운영 환경에 각각 등록하세요. 프론트엔드 번들에 들어간 값은 사용자가 볼 수 있으므로 접두사가 붙었다는 이유만으로 비밀이 되지 않습니다.

변수 이름, 등록 환경, 사용하는 코드 위치를 짧은 표로 관리하면 누락을 줄일 수 있습니다. 배포가 실패하면 값을 답변이나 로그에 복사하기보다 “변수 존재 여부”와 “적용 환경”부터 확인합니다.

4단계: 운영 전에 미리보기 URL로 검증합니다

첫 Vercel 배포를 끝내는 순서

실습용 Next.js 저장소를 준비하고 로컬 빌드가 통과한 커밋을 사용합니다. Vercel에서 새 프로젝트를 만들고 해당 저장소를 연결한 뒤 프레임워크 감지 결과, Root Directory, 빌드 명령을 확인하세요. 서비스에 필요한 환경 변수는 대상 환경에 등록한 뒤 배포합니다.

1. 배포 로그에서 의존성 설치·빌드·배포 단계가 끝나는지 확인합니다.
2. 발급된 배포 URL에서 홈과 하위 경로를 직접 열고 새로고침합니다.
3. 별도 실습 브랜치의 Preview에서 환경 변수가 누락된 경우를 점검합니다. 오류 로그에 어떤 변수 이름이 누락되었는지 확인하되 값은 출력하지 않습니다.
4. Preview 환경에 올바른 값을 등록하고 새로 배포합니다. 기존 배포에는 바뀐 값이 소급 적용되지 않습니다.
5. 수정한 URL에서 같은 동작을 다시 확인하고 정상 커밋·배포 ID를 기록합니다.

복구가 필요하면 프로젝트의 이전 성공 배포와 현재 배포를 비교한 뒤 제공되는 Rollback 동작으로 이전 성공본을 복원합니다. 롤백은 해당 빌드와 설정으로 돌아가는 동작이며 데이터베이스 변경을 되돌리지 않습니다. 복구 뒤 운영 URL과 환경 설정의 일치 여부를 다시 검사하세요. 이 절은 실습 절차이며 운영 장애나 실제 배포 성공을 대신 보고하는 내용은 아닙니다. 배포 안내, 환경 변수 변경, 롤백 범위를 확인하세요.

Git 저장소를 연결하면 브랜치나 PR 단위의 미리보기 배포를 활용할 수 있습니다. 운영 데이터에 연결하지 않은 상태에서 로그인 리디렉션, 동적 라우팅, 이미지 도메인, 새로고침, 404 페이지를 먼저 검사하세요.

• 직접 URL을 입력하거나 새로고침해도 라우팅이 유지되는가
• API·이미지·폰트가 HTTPS와 올바른 도메인에서 로드되는가
• 미리보기 환경의 OAuth 허용 도메인과 callback URL이 맞는가
• 소스맵·로그·오류 화면에 비밀 값이 노출되지 않는가

5단계: 운영 도메인과 캐시·보안을 설정합니다

운영 배포가 끝나면 커스텀 도메인, HTTPS, 대표 도메인 리디렉션을 확인합니다. www와 루트 도메인이 모두 열리더라도 한쪽을 대표 URL로 정하고 나머지는 301로 연결해야 중복 URL을 줄일 수 있습니다.

정적 자산은 긴 캐시를 적용할 수 있지만 HTML과 배포 직후 바뀌어야 하는 데이터까지 같은 기준으로 캐시하면 이전 화면이 남을 수 있습니다. 플랫폼 기본값을 이해한 뒤 필요한 경로만 헤더를 조정하세요.

6단계: 배포 성공 메시지 뒤에 실제 사용자 경로를 확인합니다

배포 상태가 성공이어도 로그인, 결제 전 단계, 이미지 업로드, 동적 상세 페이지는 실패할 수 있습니다. 홈 한 장만 열어보지 말고 사용자가 실제로 이동하는 핵심 경로를 데스크톱과 모바일에서 확인하세요.

문제가 생기면 빌드·런타임·라우팅·권한 중 어느 단계인지 먼저 분리합니다. 공통 진단 순서는 프론트엔드 배포 오류 체크리스트를 사용하고, Vercel 빌드 자체가 실패하면 Vercel Next.js 빌드 오류 체크리스트로 이동하면 됩니다.

프로젝트별 완료 기준

1. 정적 사이트: 빌드 출력 폴더, SPA rewrite, 404, 캐시 헤더를 설명할 수 있습니다.
2. Next.js 앱: 정적·동적 렌더링과 서버 런타임 필요 여부를 구분하고 미리보기에서 검증합니다.
3. Firebase 연동 앱: Auth 허용 도메인, 보안 규칙, Hosting 또는 App Hosting 선택 이유를 설명합니다.
4. 운영 배포: 도메인·HTTPS·환경 변수·로그·롤백 경로를 확인합니다.

여기까지 마치면 “어디에 배포했는가”가 아니라 “왜 그 플랫폼을 골랐고, 실패를 어느 단계에서 진단하는가”를 설명할 수 있습니다. Next.js 운영 성능까지 이어서 점검하려면 Next.js 성능 최적화 체크리스트를 참고하세요.

하나의 요구사항을 배포 결정과 검증 기록으로 바꾸기

가정한 프로젝트는 로그인 후 개인 학습 노트를 보는 Next.js 앱입니다. /help는 공개 문서이고 /notes는 요청 쿠키로 사용자를 식별합니다. 이 앱을 정적 파일로만 export하면 /notes의 서버 인증 요구사항을 충족할 수 없습니다. Vercel이나 App Hosting처럼 해당 서버 실행을 지원하는 경로를 먼저 검토합니다. 반대로 API 호출과 인증을 모두 브라우저에서 처리하는 Vite 앱은 Hosting의 정적 배포 후보입니다. 이는 특정 업체의 우열이 아니라 실행 위치에 따른 선택입니다.

남길 항목	예시·확인 방법
검증할 커밋	Git 커밋 ID와 배포 ID를 함께 기록
설치 재현	lockfile과 Node/npm 버전, 실제 실행한 설치 명령
라우팅	홈·직접 입력한 하위 경로·존재하지 않는 경로의 상태
인증	비로그인 접근·로그인·로그아웃 후 직접 접근
환경	변수 이름과 적용 환경만 기록, 값은 기록하지 않음
복구	이전 성공 배포 ID, 되돌릴 코드 범위, 별도 DB 변경 여부

로컬 실행 명령도 스택에 맞춰 읽어야 합니다. npm run lint와 npm run start는 package.json에 해당 스크립트가 있을 때만 실행합니다. Vite는 보통 build 후 preview로 결과를 확인하며, Next.js 서버 배포는 build 후 start를 사용합니다. 스크립트가 없다는 오류를 호스팅 장애로 오해하지 마세요. 설치 후 빌드, 그 빌드의 실행 순으로 검사해야 개발 서버의 성공과 구분할 수 있습니다.

복구 연습은 운영 장애를 일부러 만드는 방식일 필요가 없습니다. 미리보기에서 잘못된 하위 경로 링크를 만든 커밋과 이를 고친 커밋을 비교하고, 같은 URL 목록을 두 버전에서 검사해 보세요. 롤백은 이전 배포를 다시 연결하는 작업이므로 데이터베이스 스키마·외부 저장소의 변경까지 되돌아간다고 가정하면 안 됩니다. 이전 코드가 현재 데이터와 호환되는지도 따로 확인해야 합니다.

완료 기준은 “배포 버튼이 성공했다”가 아니라 기록한 사용자 경로를 통과했고 문제 시 어느 배포로 돌아갈지 설명할 수 있는 상태입니다. 본문은 선택·운영 설계 안내이며 이 회차에 실제 클라우드 배포나 롤백을 실행한 결과는 아닙니다. 정적/SSR 배포 비교로 선택을 좁히고, 빌드 오류 글로 첫 실패를 추적하세요.

공식 문서 확인일: 2026-09-13. vercel.com 공식 자료 1 · vercel.com 공식 자료 2 · firebase.google.com 공식 자료 3 · firebase.google.com 공식 자료 4

공식 문서

• Vercel: Next.js on Vercel
• Firebase Hosting 시작하기
• Firebase App Hosting 시작하기
• Firebase App Hosting 비용