목표#
- 빌드 로그에서 실제 원인을 찾는 방법을 익힙니다.
- GitHub + Vercel 배포에서 자주 겪는 오류의 원인과 해결법을 빠르게 찾아봅니다.
사전 조건#
- Vercel 프로젝트의 Deployments 탭에 접근할 수 있습니다.
1. 빌드 로그 읽는 법#
- Vercel Deployments 탭에서 실패한 배포(빨간색 Error)를 누릅니다.
- Build Logs 영역을 펼칩니다.
로그를 아래에서 위로 읽으면서 처음 나타나는 오류 메시지를 찾습니다.
- 맨 마지막 줄(
Command "npm run build" exited with 1)은 "빌드가 실패했다"는 결과일 뿐, 원인이 아닙니다. - 그 위쪽의
Error:,Failed to compile,Module not found같은 줄이 진짜 원인입니다.
- 맨 마지막 줄(
가장 빠른 진단법은 로컬에서 똑같이 빌드해 보는 것입니다. Vercel과 비슷한 조건으로 실행하려면 의존성을 새로 설치한 뒤 빌드합니다.
npm ci
npm run buildnpm ci는 package-lock.json 그대로 깨끗하게 설치합니다. (기존 node_modules를 지우고 설치)
2. 빌드 실패#
2-1. Module not found / Cannot find module — 파일 이름 대소문자#
증상: 로컬(Windows/macOS)에서는 잘 되는데 Vercel에서만 파일을 못 찾음
원인: Windows와 macOS는 기본적으로 파일 이름의 대소문자를 구분하지 않지만, Vercel 빌드 환경(Linux)은 구분합니다.
// 실제 파일: components/Header.tsx
import Header from './components/header'; // ❌ Vercel에서 실패
import Header from './components/Header'; // ✅해결:
- import 경로와 실제 파일 이름의 대소문자를 똑같이 맞춥니다.
파일 이름의 대소문자만 바꿨다면 Git이 변경을 감지하지 못할 수 있습니다.
git mv로 바꿉니다.git mv components/header.tsx components/Header.tsx git commit -m "Header 파일 이름 대소문자 수정" git push
2-2. Module not found — 의존성 누락#
원인: 로컬에는 설치되어 있지만 package.json에 기록되지 않은 패키지
해결: 패키지를 정식으로 설치해 package.json과 잠금 파일에 기록한 뒤 커밋합니다.
npm install <패키지 이름>
git add package.json package-lock.json
git commit -m "누락된 의존성 추가"
git push2-3. Node.js 버전 불일치#
증상: The engine "node" is incompatible with this module, 또는 문법 오류처럼 보이는 실패
해결: 로컬 버전(node --version)을 확인하고 package.json의 engines.node로 맞춥니다. → 4장 6단계
2-4. 잠금 파일 문제#
증상: npm ci can only install packages when your package.json and package-lock.json are in sync
원인: package.json을 고친 뒤 잠금 파일을 갱신하지 않았거나, 잠금 파일을 커밋하지 않음
해결:
npm install
git add package-lock.json
git commit -m "잠금 파일 갱신"
git push저장소에 package-lock.json, yarn.lock, pnpm-lock.yaml이 여러 개 있으면 하나만 남기고 지우세요. → 4장
2-5. 린트(ESLint)·타입(TypeScript) 오류로 빌드 실패#
증상: Failed to compile, Type error:, ESLint: ...
원인: 프레임워크가 빌드 중 코드 검사를 하며, 오류가 있으면 빌드를 멈춥니다. Create React App은 CI 환경에서 경고(warning)도 오류로 처리합니다.
해결: 로그에 표시된 파일·줄 번호의 코드를 수정합니다. 로컬에서 npm run build가 통과하는지 확인 후 push합니다.
검사를 끄는 설정(예: CI=false, 타입 검사 무시 옵션)으로 빌드를 통과시킬 수는 있지만, 실제 버그를 숨기게 됩니다. 원인 코드를 고치는 것을 우선하세요.
2-6. 환경 변수가 없어 빌드 실패#
증상: Missing required environment variable, Invalid URL, 빌드 중 undefined 관련 오류
해결: Settings → Environment Variables에 값을 등록하고, 해당 환경(Production/Preview) 에 체크한 뒤 재배포합니다. → 5장
3. 배포는 성공했는데 사이트가 이상해요#
3-1. 404: NOT_FOUND#
| 확인할 것 | 해결 |
|---|---|
| Output Directory가 실제 빌드 결과 폴더와 같은가? | 로컬 빌드 결과 폴더(dist, build 등)로 수정 → 4장 |
| Framework Preset이 올바른가? | 실제 프레임워크로 변경 후 재배포 |
순수 HTML이라면 index.html이 최상단(또는 public/)에 있는가? | 파일 위치 이동 또는 Root Directory 설정 |
| Root Directory가 맞는가? | 하위 폴더 프로젝트라면 해당 폴더 지정 |
3-2. 첫 화면은 되는데 다른 주소에서 새로고침하면 404 (SPA)#
React Router 등 클라이언트 라우팅을 쓰는 Vite/CRA 프로젝트에서 발생합니다. vercel.json에 rewrites를 추가합니다. → 4장 7단계
3-3. 화면이 하얗게만 나옴#
- 브라우저에서 F12 → Console 탭의 빨간 오류를 확인합니다.
자주 있는 원인:
- 브라우저용 환경 변수가
undefined→ 노출 접두사(NEXT_PUBLIC_,VITE_) 확인, 재배포 → 5장 - Vite의
base설정이 다른 값(예: GitHub Pages용/repo-name/)으로 되어 있음 →/로 수정
- 브라우저용 환경 변수가
3-4. 이미지·CSS가 깨짐#
- 파일 경로의 대소문자를 확인합니다. (
Logo.PNG≠logo.png) → 2-1 참고 - 정적 파일이 프레임워크가 지정한 폴더(보통
public/)에 있는지 확인합니다.
3-5. 코드를 고쳤는데 예전 화면이 보임#
- 브라우저 강력 새로고침: Windows
Ctrl + Shift + R, macOSCmd + Shift + R - Vercel Deployments 탭에서 최신 배포가 Production이고 Ready인지 확인합니다.
- 롤백 후 자동 배포가 멈춘 상태가 아닌지 확인합니다. → 6장
- 그래도 같다면 Redeploy에서 빌드 캐시를 사용하지 않는 옵션으로 재배포합니다.
4. 자동 배포가 안 돼요#
4-1. push해도 새 배포가 생기지 않음#
| 확인할 것 | 해결 |
|---|---|
| GitHub에 실제로 push되었는가? | GitHub 저장소에서 최신 커밋 확인, git push 출력 확인 |
| Vercel 프로젝트가 올바른 저장소에 연결되어 있는가? | 프로젝트 Settings → Git에서 연결된 저장소 확인 |
| GitHub App이 해당 저장소에 접근할 수 있는가? | GitHub Settings → Applications → Installed GitHub Apps → Vercel → Configure → 2장 |
| Ignored Build Step 설정 때문에 건너뛰었는가? | Deployments 탭에 Canceled/Ignored 배포가 있는지 확인 |
4-2. 다른 사람이 push한 커밋의 배포가 막힘#
원인: 개인(Hobby) 계정의 Private 저장소에서는 프로젝트 소유자가 아닌 사람의 커밋으로 생성된 배포가 차단될 수 있습니다.
해결:
- 커밋 작성자 이메일(
git config user.email)이 Vercel 계정과 연결된 GitHub 계정 이메일과 같은지 확인합니다. - 팀으로 협업한다면 Vercel 팀(Pro 요금제 등)을 만들고 구성원을 초대하는 방법을 검토합니다.
4-3. main이 아닌 브랜치가 Production으로 배포됨 / main이 Preview로 배포됨#
Production 브랜치 설정을 확인합니다. → 6장 1단계
5. 기타#
5-1. FUNCTION_INVOCATION_TIMEOUT / 서버 함수가 느림#
API Route 등 서버 함수가 제한 시간 안에 응답하지 못한 경우입니다. 외부 API 호출 지연, 무한 대기를 확인하고, 필요하면 함수 최대 실행 시간 설정을 검토합니다. 제한은 요금제마다 다릅니다. → Vercel Limits
5-2. 사용량 제한 초과 알림#
Hobby 요금제에는 대역폭, 빌드 시간, 함수 실행 등 사용량 제한이 있습니다. Vercel 대시보드의 Usage 메뉴에서 사용량을 확인하세요. → Vercel Limits
6. 그래도 해결되지 않을 때#
- 빌드 로그의 첫 번째 오류 메시지를 그대로 복사해 검색합니다.
- Vercel 상태 페이지에서 장애가 있는지 확인합니다.
- Vercel Community에서 비슷한 사례를 찾거나 질문합니다.
- Vercel 지원 센터에 문의합니다.
질문 글에 로그를 붙일 때 API 키, 토큰, 이메일 등 민감 정보가 들어 있지 않은지 반드시 확인하세요.
빠른 진단표#
| 증상 | 바로 가기 |
|---|---|
Module not found | 2-1, 2-2 |
engine "node" is incompatible | 2-3 |
npm ci can only install... | 2-4 |
Failed to compile / Type error | 2-5 |
| 환경 변수 관련 오류 | 2-6, 5장 |
404: NOT_FOUND | 3-1 |
| 새로고침 시 404 | 3-2 |
| 하얀 화면 | 3-3 |
| push해도 배포 안 됨 | 4-1 |
| 도메인 연결 문제 | 7장 문제 해결 |
| CLI 오류 | 8장 문제 해결 |
다음 단계#
🎉 매뉴얼을 모두 마쳤습니다. 처음으로 돌아가려면 README를 참고하세요.