프론트엔드 배포 오류를 Vercel, Vite, Expo 기준으로 빠르게 분류하기
이 글은 프론트엔드 배포 오류 해결의 대표 허브입니다. Vercel, Vite, Expo, Firebase Hosting처럼 비슷해 보이는 배포 문제를 단계별로 나누고 각 상세 해결 글로 연결합니다.
프론트엔드 배포 오류를 단계별로 확인하는 순서
이 글은 프론트엔드 배포 오류 해결의 대표 허브입니다. Vercel, Vite, Expo, Firebase Hosting처럼 비슷해 보이는 배포 문제를 단계별로 나누고 각 상세 해결 글로 연결합니다.
- 1단계 · 배포 방식 선택 · 프론트엔드 배포 로드맵
- 2단계 · Vercel 빌드 실패 · Vercel Next.js 배포 실패 체크리스트
- 3단계 · 배포 후 404 라우팅 · Vercel 404 NOT_FOUND 오류 해결
- 4단계 · Next.js 환경변수 · Next.js 환경변수 적용 오류 해결
- 5단계 · Vite 환경변수 · Vite import.meta.env undefined 해결
- 6단계 · Expo 원격 빌드 · Expo EAS Build 오류 해결
- 7단계 · Firebase 배포 방식 비교 · Firebase Hosting App Hosting 차이
문제 상황 요약
배포 오류를 볼 때는 “배포가 실패했다”로 묶지 말고 install, build, runtime, routing, environment, native build 단계로 나눠야 합니다. Vercel은 build log와 runtime log를 구분하고, Vite는 env 파일과 prefix를 확인하며, Expo는 로컬 개발 환경과 EAS 원격 빌드 환경 차이를 봐야 합니다.
문제 상황별 프론트엔드 배포 오류 글
배포 오류는 install, build, runtime, routing, environment, native build 단계로 나눠야 빨리 해결됩니다. 아래 표에서 현재 막힌 단계와 에러 메시지 위치를 먼저 맞춰 보세요.
| 문제 상황 | 먼저 확인할 위치 | 연결 글 |
|---|---|---|
| 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에서 import.meta.env가 undefined | VITE_ prefix, env 파일 위치, 배포 env 등록 | Vite import.meta.env undefined 해결 |
| Expo EAS Build가 로컬과 다르게 실패 | eas.json, app config, credentials, SDK 버전 | Expo EAS Build 오류 해결 |
| Next.js build 중 Suspense/useSearchParams 오류 발생 | client component, Suspense boundary, App Router build rules | Next.js useSearchParams Suspense build error |
| Firebase Hosting과 App Hosting 중 어떤 배포 방식을 써야 할지 헷갈림 | 정적 배포, SSR 필요 여부, Firebase 연결 방식 | Firebase Hosting App Hosting 차이 |
배포 오류 해결 순서
- install 단계, build 단계, runtime 단계 중 어디서 실패했는지 먼저 나눕니다.
- 첫 번째 에러 메시지를 찾고, 마지막 실패 문구만 보고 판단하지 않습니다.
- 로컬에서 production build를 재현해 코드 문제인지 환경 차이인지 분리합니다.
- 환경변수, Node 버전, package manager, lock 파일을 확인합니다.
- 배포 후에만 터지면 runtime logs, Network 탭, API URL을 확인합니다.
문제 상황별로 이어서 읽기
Vercel·Next.js 배포 문제
- Vercel Next.js 배포 실패 해결 체크리스트
- Vercel 404 NOT_FOUND 오류 해결: Next.js 배포 후 라우팅과 rewrites 확인하기
- Next.js useSearchParams Suspense build error
환경변수·빌드 설정 문제
Expo·Firebase 배포 선택 문제
- Expo EAS Build 오류 해결
- Firebase Hosting App Hosting 차이: 정적 배포와 SSR 기준
- 프론트엔드 배포 로드맵: Vercel, Firebase Hosting, App Hosting 기준
실무 체크리스트
- 로컬에서 production build를 실행해 같은 오류가 나는지 확인합니다.
- 배포 플랫폼의 환경변수가 Preview/Production에 모두 필요한 만큼 등록되어 있는지 확인합니다.
- Node.js 버전과 package manager, lock 파일을 하나의 기준으로 맞춥니다.
- build 성공 후 runtime 오류는 build logs가 아니라 function/runtime logs를 봅니다.
- Expo는 로컬 Expo Go와 EAS 원격 빌드 환경을 분리해서 확인합니다.
자주 묻는 질문
로컬에서는 되는데 배포에서만 실패하면 어디부터 보나요?
먼저 로컬 production build로 재현하고, 재현되지 않으면 환경변수, Node 버전, package manager, lock 파일, 배포 플랫폼 cache 순서로 봅니다.
Vite 환경변수는 왜 배포에서만 undefined가 되나요?
.env.local은 로컬 전용이고 배포 플랫폼에 자동 반영되지 않기 때문입니다. 배포 환경에 VITE_ prefix가 붙은 값을 별도로 등록해야 합니다.
Expo Go에서는 되는데 EAS Build가 실패할 수 있나요?
가능합니다. Expo Go는 개발 런타임이고 EAS Build는 원격 네이티브 빌드이므로 credentials, native config, SDK 호환성 문제가 따로 드러날 수 있습니다.