Firebase배포 / 서버프론트엔드

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

2026.05.11·수정 2026.07.19·약 13분
작성자:

프론트엔드 배포 오류 해결 글을 한곳에서 찾는 허브

이 글은 Vercel, Netlify, Firebase, 환경변수, 404, 500, 빌드 실패처럼 자주 겹치는 프론트엔드 배포 오류를 install, build, runtime, routing, environment 단계로 나누고, 바로 이어서 볼 해결 글과 공식 확인 위치로 연결하는 허브입니다.

에러 메시지별 빠른 진단표

배포 오류는 “배포가 안 된다”로 묶으면 해결 순서가 흐려집니다. 먼저 첫 실패 지점이 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 필요 여부, .firebaseignore, Functions 연결 Firebase Hosting App Hosting 차이 / Firebase .firebaseignore 작성법

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 연결을 봅니다. 배포 제외 파일은 .firebaseignore에서 먼저 확인합니다.
  • 환경변수: 로컬 .env.local과 배포 플랫폼 환경변수는 별개입니다. 클라이언트에서 읽어야 하는 값은 NEXT_PUBLIC_ 또는 VITE_ prefix가 필요합니다.
  • 404/500: 404는 라우팅·rewrite·빌드 결과를, 500은 서버 함수·API Route·Firebase Admin/Secret 설정을 먼저 봅니다.

문제 상황 요약

프론트엔드 배포 오류 허브: Vercel Netlify Firebase 환경변수 404 500 원인 진단 흐름

배포 오류를 볼 때는 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 배포 문제

환경변수·빌드 설정 문제

Netlify·Firebase·Expo 배포 선택 문제

실무 체크리스트

  • 로컬에서 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 문서를 기준으로 다시 확인합니다.

함께 읽으면 좋은 글

Firebase 카테고리의 다른 글

이 글이 마음에 드세요?

RSS 피드를 구독하세요!

댓글 남기기