프론트엔드 배포 오류 해결 허브: Vercel, Netlify, Firebase 체크리스트

• 에러 메시지별 빠른 진단표
• 플랫폼별로 먼저 볼 위치
• 문제 상황 요약
• 문제 상황별 프론트엔드 배포 오류 글
• 배포 오류 해결 순서
• 관련 배포 오류 해결 글
• 실무 체크리스트
• 자주 묻는 질문

에러 메시지별 빠른 진단표

배포 오류는 “배포가 안 된다”로 묶으면 해결 순서가 흐려집니다. 먼저 첫 실패 지점이 install, build, runtime, routing, environment 중 어디인지 표시하고, 화면에 보이는 404, 500, 환경변수, 빌드 실패, 플랫폼 설정 문제를 관련 글과 공식 로그 위치에 연결하는 편이 빠릅니다.

에러 상황	우선 확인할 것	관련 글
배포 후 404 또는 NOT_FOUND 발생	라우팅 파일, 빌드 결과, dynamic route, rewrite/redirect 설정	Vercel 404 NOT_FOUND 오류 해결
환경변수 오류 또는 값이 undefined	.env.local, Vercel/Netlify 환경변수 등록, NEXT_PUBLIC_, VITE_ prefix	Next.js 환경변수 적용 오류 / Vite import.meta.env undefined
500 오류 또는 서버 함수 실패	API Route/Route Handler, 서버 함수 로그, Firebase Functions, Admin SDK 설정, Secret	Firebase Functions v2 사용법 / Next.js Route Handler 오류 해결
빌드 실패	TypeScript, ESLint, package 버전, lock 파일, Node 버전, peer dependency	Vercel Next.js 배포 실패 체크리스트 / npm ERESOLVE 의존성 충돌 해결
Vercel에서만 실패	Build Logs와 Runtime Logs를 분리하고, Preview/Production 환경변수와 framework preset을 확인	Vercel Next.js 배포 실패 체크리스트
Netlify에서만 실패	build command, publish directory, base directory, deploy log, Node 버전, Vite 환경변수	프론트엔드 배포 로드맵 / Vite 환경변수 오류 해결
Firebase 배포 설정이 헷갈림	정적 Hosting, App Hosting의 동적 웹 앱 지원, SSR 필요 여부, firebase.json의 hosting.ignore, Functions 연결	Firebase Hosting App Hosting 차이 / Firebase 배포 제외 설정 작성법

Vercel, Netlify, Firebase별로 먼저 볼 위치

• Vercel: Build Logs와 Runtime Logs를 나눠 봅니다. build 실패면 package/TypeScript/환경변수, 배포 후 오류면 routing, rewrite, serverless function 로그를 확인합니다. 공식 문서 기준으로 Build Logs는 배포 실패 원인 확인용이고, Runtime Logs는 실행 중 요청과 함수 오류를 보는 위치입니다.
• Netlify: build command와 publish directory가 맞는지 먼저 봅니다. monorepo나 하위 폴더 프로젝트라면 base directory와 package directory도 함께 확인합니다. Vite 프로젝트라면 VITE_ prefix와 Netlify 환경변수 등록 여부를 같이 봅니다.
• Firebase: 정적 사이트는 Firebase Hosting, 동적 웹 앱이나 프레임워크 기반 SSR 흐름은 App Hosting, 별도 HTTP/server 로직은 Functions 연결을 봅니다. 배포 제외 파일은 firebase.json의 hosting.ignore에서 먼저 확인합니다.
• 환경변수: 로컬 .env.local과 배포 플랫폼 환경변수는 별개입니다. 클라이언트에서 읽어야 하는 값은 NEXT_PUBLIC_ 또는 VITE_ prefix가 필요합니다.
• 404/500: 404는 라우팅·rewrite·빌드 결과를, 500은 서버 함수·API Route·Firebase Admin/Secret 설정을 먼저 봅니다.

문제 상황 요약

배포 오류를 볼 때는 install, build, runtime, routing, environment, native build 단계를 분리해야 합니다. Vercel은 Build Logs와 Runtime Logs를 구분하고, Netlify는 build command, publish directory, base directory를 확인하며, Firebase는 Hosting, App Hosting, Functions의 역할 차이를 먼저 나눠 봅니다. Vite 앱은 어느 플랫폼이든 클라이언트 번들에서 읽는 환경변수에 VITE_ prefix가 필요한지도 같이 확인합니다.

문제 상황별 프론트엔드 배포 오류 글

아래 표는 에러 메시지와 플랫폼 기준으로 관련 글을 다시 묶은 목록입니다. 같은 환경변수 오류라도 Next.js와 Vite의 prefix 규칙이 다르고, 같은 배포 실패라도 build 단계와 runtime 단계의 확인 위치가 다릅니다.

문제 상황	먼저 확인할 위치	연결 글
Vercel Next.js 배포가 build 단계에서 실패	Build Logs, Node 버전, lock 파일, 환경변수	Vercel Next.js 배포 실패 체크리스트
배포 후 특정 URL이 404 또는 NOT_FOUND로 뜸	Vercel routes, Next.js rewrites, dynamic route 파일	Vercel 404 NOT_FOUND 오류 해결
.env.local 수정 후 값이 안 바뀌거나 배포에서 env가 비어 있음	dev server 재시작, NEXT_PUBLIC_, Preview/Production env	Next.js 환경변수 적용 오류 해결
Vite/Netlify에서 import.meta.env가 undefined	VITE_ prefix, env 파일 위치, Netlify/Vercel env 등록	Vite import.meta.env undefined 해결
500 오류가 서버 함수 또는 Firebase 연결에서 발생	Functions 로그, Secret, Admin SDK, API Route/Route Handler	Firebase Functions v2 사용법
Next.js API/Route Handler 메서드 오류	route.ts, GET/POST export, 호출 URL	Next.js Route Handler 405 오류 해결
Expo EAS Build가 로컬과 다르게 실패	eas.json, app config, credentials, SDK 버전	Expo EAS Build 오류 해결
Firebase Hosting과 App Hosting 중 어떤 배포 방식을 써야 할지 헷갈림	정적 배포, SSR 필요 여부, Firebase 연결 방식	Firebase Hosting App Hosting 차이

배포 오류 해결 순서

1. 에러가 install, build, runtime, routing, environment 중 어느 단계에서 발생했는지 먼저 표시합니다.
2. 배포 플랫폼의 첫 번째 실패 로그를 찾고, build log와 runtime log를 섞어 판단하지 않습니다.
3. 로컬에서 production build를 재현해 코드 문제인지 배포 환경 차이인지 분리합니다.
4. 환경변수, Node 버전, package manager, lock 파일을 하나의 기준으로 맞춥니다.
5. 배포 후에만 터지면 runtime logs, Network 탭, API URL, serverless function 로그를 확인합니다.

관련 배포 오류 해결 글

Vercel·Next.js 배포 문제

• Vercel Next.js 배포 실패 해결 체크리스트
• Vercel 404 NOT_FOUND 오류 해결: Next.js 배포 후 라우팅과 rewrites 확인하기
• Next.js useSearchParams Suspense build error
• Next.js Route Handler 405 오류 해결

환경변수·빌드 설정 문제

• Next.js 환경변수 적용 오류 해결: .env.local을 바꿨는데 값이 안 바뀔 때
• Vite import.meta.env undefined 해결
• npm install 의존성 충돌 해결: ERESOLVE 오류가 날 때 대처 방법

Netlify·Firebase·Expo 배포 선택 문제

• 프론트엔드 배포 로드맵: Vercel, Firebase Hosting, App Hosting 기준
• Firebase Hosting App Hosting 차이: 정적 배포와 SSR 기준
• Firebase Functions v2 사용법: 트리거 배포 Secret 처리
• Firebase 배포 제외 설정 작성법: 배포 제외 파일 관리
• Expo EAS Build 오류 해결

실무 체크리스트

• 로컬에서 production build를 실행해 같은 오류가 나는지 확인하고, Netlify라면 build command와 publish directory가 실제 산출물 위치와 맞는지 확인합니다.
• 배포 플랫폼의 환경변수가 Preview/Production 등 필요한 배포 context에 등록되어 있는지 확인하고, 브라우저 번들에 노출되는 값에는 Next.js의 NEXT_PUBLIC_ 또는 Vite의 VITE_ prefix를 적용합니다.
• Node.js 버전과 package manager, lock 파일을 하나의 기준으로 맞춥니다.
• build 성공 후 runtime 오류는 build logs가 아니라 function/runtime logs를 봅니다.
• 404는 routing/rewrite/build output을, 500은 server/API/Firebase 설정을 먼저 확인합니다.
• Expo는 로컬 Expo Go와 EAS 원격 빌드 환경을 분리해서 확인합니다.

자주 묻는 질문

로컬에서는 되는데 배포에서만 실패하면 어디부터 보나요?

먼저 로컬 production build로 재현하고, 재현되지 않으면 환경변수, Node 버전, package manager, lock 파일, 배포 플랫폼 cache 순서로 봅니다. Netlify는 build command/publish directory, Vercel은 Build Logs와 Runtime Logs의 실패 지점을 분리해 확인합니다.

배포 후 404가 나면 코드 오류인가요?

항상 코드 오류는 아닙니다. 정적 빌드 결과에 해당 경로가 없는지, dynamic route가 올바른지, Vercel/Netlify rewrite 설정이 맞는지 먼저 확인해야 합니다.

500 오류는 프론트엔드 글에서 어떻게 봐야 하나요?

500은 화면 컴포넌트보다 서버 함수, API Route, Firebase Functions, Admin SDK, Secret 설정에서 시작하는 경우가 많습니다. 브라우저 콘솔보다 플랫폼 runtime log를 먼저 봅니다.

Netlify와 Vercel의 환경변수 확인 방식은 같은가요?

기본 원리는 같지만 설정 위치와 deploy context, build command, publish directory가 다릅니다. Vite는 어느 플랫폼이든 클라이언트 노출 변수에 VITE_ prefix가 필요하고, 민감한 값은 클라이언트 prefix로 노출하지 않아야 합니다.

Firebase Hosting과 App Hosting은 언제 나눠 쓰나요?

정적 SPA나 정적 사이트는 Firebase Hosting으로 충분한 경우가 많고, Next.js/Angular 같은 동적 웹 앱이나 SSR 실행 흐름은 App Hosting을 검토합니다. 특정 HTTP API나 백엔드 트리거는 Functions 연동 여부를 별도로 봅니다.

공식 기준은 Vercel Build Logs, Vercel Runtime Logs, Netlify build settings, Netlify environment variables, Firebase Hosting, Firebase App Hosting, Vite Env Variables and Modes 문서를 기준으로 다시 확인합니다.

함께 읽으면 좋은 글

• Next.js Dynamic server usage 오류 해결: cookies headers 사용 위치 확인하기
• Firebase Auth unauthorized-domain 오류 해결: 로그인 도메인 설정 확인하기
• pnpm install 오류 해결: lockfile과 workspace 의존성이 꼬였을 때 대처 방법

다섯 줄의 장애 기록으로 올바른 글 찾기

“로컬에서는 된다”만으로는 비교 조건이 부족합니다. 로컬 dev인지 production build인지, 같은 커밋인지, 같은 URL인지부터 적습니다. 다음 기록에는 비밀값·토큰·사용자 개인정보를 넣지 않습니다. 재시도마다 결과를 바꾸는 대신 한 원인 후보만 수정하면 무엇이 해결했는지 설명할 수 있습니다.

커밋 / 배포 ID: 확인한 식별자
첫 실패 단계: install | build | runtime | routing | permission
실행 명령 또는 요청 경로: 예) npm ci, /notes
첫 오류 코드와 파일 경로: 값·토큰은 제외
수정한 항목 / 같은 검사 재실행 결과:

겉으로 같은 증상	서로 다른 원인	다음 행동
404	라우트 파일 없음 / 다른 배포 URL / rewrite 목적지 없음	목적지 URL을 직접 열고 실제 배포의 파일 경로 대조
빈 데이터	정상 0행 / RLS가 필터링 / 쿼리 오류를 숨김	error와 data를 분리하고 소유자·정책 점검
500	서버 환경 변수 누락 / 외부 API 오류 / 코드 예외	같은 배포의 Runtime Logs에서 요청 시각과 경로 대조
설치 실패	lockfile 불일치 / registry 인증 / 런타임 버전	에러 종류를 확인하고 해당 파일·설정 하나만 수정

예를 들어 npm ci가 lockfile 불일치로 끝났다면 rewrite를 바꿔도 앱 빌드까지 도달하지 못합니다. 설치가 끝나고 TypeScript 오류가 발생했다면 의존성 캐시 삭제보다 오류가 가리키는 타입과 실제 데이터를 비교합니다. 반대로 빌드가 성공한 다음 특정 URL만 404이면 빌드 로그에 머무르지 말고 라우트·출력·배포 별칭을 확인합니다.

플랫폼 이름이 달라도 비교 단위는 같습니다. Vercel에서는 해당 Deployment의 Build/Runtime Logs, Netlify에서는 해당 Deploy의 설치·빌드 로그, Firebase에서는 Hosting 출력 설정 또는 App Hosting 빌드·런타임을 구분합니다. 최신 배포 화면을 열었다고 가정하지 말고 사용자에게 보이는 URL이 그 배포를 가리키는지 확인해야 합니다.

수정 후에는 처음 실패했던 명령·URL을 그대로 재실행하고 홈, 하위 경로 직접 접근, 없는 경로, 핵심 사용자 기능을 추가 확인합니다. 성공 로그를 얻었어도 외부 인증·결제·권한 검사를 하지 않았다면 그 항목은 미확인으로 남깁니다. 이 허브 자체는 장애를 재현한 결과 보고가 아니라 진단 분류 도구입니다. npm ci 최소 재현과 404 수정 실험에서 각 분기의 실제 절차를 이어서 확인하세요.

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