배포 매뉴얼
전체 목차09 · 문제 해결
Chapter 09

문제 해결

최종 확인일 2026-11-04 읽는 시간 약 9분 부록 · 도구와 문제 해결

목표#

  • 빌드 로그에서 실제 원인을 찾는 방법을 익힙니다.
  • GitHub + Vercel 배포에서 자주 겪는 오류의 원인과 해결법을 빠르게 찾아봅니다.

사전 조건#

  • Vercel 프로젝트의 Deployments 탭에 접근할 수 있습니다.

1. 빌드 로그 읽는 법#

  1. Vercel Deployments 탭에서 실패한 배포(빨간색 Error)를 누릅니다.
  2. Build Logs 영역을 펼칩니다.
  3. 로그를 아래에서 위로 읽으면서 처음 나타나는 오류 메시지를 찾습니다.

    • 맨 마지막 줄(Command "npm run build" exited with 1)은 "빌드가 실패했다"는 결과일 뿐, 원인이 아닙니다.
    • 그 위쪽의 Error:, Failed to compile, Module not found 같은 줄이 진짜 원인입니다.
팁

가장 빠른 진단법은 로컬에서 똑같이 빌드해 보는 것입니다. Vercel과 비슷한 조건으로 실행하려면 의존성을 새로 설치한 뒤 빌드합니다.

bash
npm ci
npm run build

npm ci는 package-lock.json 그대로 깨끗하게 설치합니다. (기존 node_modules를 지우고 설치)


2. 빌드 실패#

2-1. Module not found / Cannot find module — 파일 이름 대소문자#

증상: 로컬(Windows/macOS)에서는 잘 되는데 Vercel에서만 파일을 못 찾음

원인: Windows와 macOS는 기본적으로 파일 이름의 대소문자를 구분하지 않지만, Vercel 빌드 환경(Linux)은 구분합니다.

JavaScript
// 실제 파일: components/Header.tsx
import Header from './components/header'; // ❌ Vercel에서 실패
import Header from './components/Header'; // ✅

해결:

  1. import 경로와 실제 파일 이름의 대소문자를 똑같이 맞춥니다.
  2. 파일 이름의 대소문자만 바꿨다면 Git이 변경을 감지하지 못할 수 있습니다. git mv로 바꿉니다.

    bash
    git mv components/header.tsx components/Header.tsx
    git commit -m "Header 파일 이름 대소문자 수정"
    git push

2-2. Module not found — 의존성 누락#

원인: 로컬에는 설치되어 있지만 package.json에 기록되지 않은 패키지

해결: 패키지를 정식으로 설치해 package.json과 잠금 파일에 기록한 뒤 커밋합니다.

bash
npm install <패키지 이름>
git add package.json package-lock.json
git commit -m "누락된 의존성 추가"
git push

2-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을 고친 뒤 잠금 파일을 갱신하지 않았거나, 잠금 파일을 커밋하지 않음

해결:

bash
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. 화면이 하얗게만 나옴#

  1. 브라우저에서 F12 → Console 탭의 빨간 오류를 확인합니다.
  2. 자주 있는 원인:

    • 브라우저용 환경 변수가 undefined → 노출 접두사(NEXT_PUBLIC_, VITE_) 확인, 재배포 → 5장
    • Vite의 base 설정이 다른 값(예: GitHub Pages용 /repo-name/)으로 되어 있음 → /로 수정

3-4. 이미지·CSS가 깨짐#

  • 파일 경로의 대소문자를 확인합니다. (Logo.PNG ≠ logo.png) → 2-1 참고
  • 정적 파일이 프레임워크가 지정한 폴더(보통 public/)에 있는지 확인합니다.

3-5. 코드를 고쳤는데 예전 화면이 보임#

  1. 브라우저 강력 새로고침: Windows Ctrl + Shift + R, macOS Cmd + Shift + R
  2. Vercel Deployments 탭에서 최신 배포가 Production이고 Ready인지 확인합니다.
  3. 롤백 후 자동 배포가 멈춘 상태가 아닌지 확인합니다. → 6장
  4. 그래도 같다면 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. 그래도 해결되지 않을 때#

  1. 빌드 로그의 첫 번째 오류 메시지를 그대로 복사해 검색합니다.
  2. Vercel 상태 페이지에서 장애가 있는지 확인합니다.
  3. Vercel Community에서 비슷한 사례를 찾거나 질문합니다.
  4. Vercel 지원 센터에 문의합니다.
주의

질문 글에 로그를 붙일 때 API 키, 토큰, 이메일 등 민감 정보가 들어 있지 않은지 반드시 확인하세요.


빠른 진단표#

증상바로 가기
Module not found2-1, 2-2
engine "node" is incompatible2-3
npm ci can only install...2-4
Failed to compile / Type error2-5
환경 변수 관련 오류2-6, 5장
404: NOT_FOUND3-1
새로고침 시 4043-2
하얀 화면3-3
push해도 배포 안 됨4-1
도메인 연결 문제7장 문제 해결
CLI 오류8장 문제 해결

다음 단계#

🎉 매뉴얼을 모두 마쳤습니다. 처음으로 돌아가려면 README를 참고하세요.

참고 자료#