Choorai | 문서
배포 전 필수 해결

빌드 실패 해결하기

"npm run build exited with code 1" 에러가 발생했나요? 코드에 문제가 있거나 의존성이 누락되었을 수 있습니다.

TL;DR (핵심 요약)

1) 에러 메시지를 잘 읽으세요 (어떤 파일, 몇 번째 줄) 2) TypeScript 에러면 타입 문제 3) Module not found면 패키지 설치 필요 4) npm install 후 다시 빌드

심각코드: BUILD_FAIL

Error: Command "npm run build" exited with 1

원인

빌드 스크립트 실행 중 오류가 발생했습니다. TypeScript 타입 에러, 누락된 모듈, 구문 오류 등이 원인일 수 있습니다.

해결책
  1. 터미널에서 에러 메시지 전체를 확인하세요
  2. 에러가 발생한 파일과 줄 번호를 찾으세요
  3. 로컬에서 npm run build를 실행해 같은 에러가 나는지 확인
  4. 에러 메시지를 AI에게 복사해서 물어보세요
주의

Module not found: Can't resolve 'package-name'

원인

코드에서 import한 패키지가 설치되지 않았습니다.

해결책
npm install package-name
주의

Type error: Property 'xxx' does not exist on type 'yyy'

원인

TypeScript가 타입 불일치를 감지했습니다. 변수나 함수의 타입이 맞지 않습니다.

해결책
  1. 해당 변수의 타입을 확인하세요
  2. 타입 정의가 누락되었다면 추가하세요
  3. any 타입으로 임시 해결 가능 (비추천)

자주 발생하는 빌드 에러

1. 의존성 문제

터미널
# node_modules 삭제 후 재설치
rm -rf node_modules package-lock.json
npm install

# 또는 캐시 정리
npm cache clean --force
npm install

2. 환경 변수 누락

빌드 시 필요한 환경 변수가 없으면 실패합니다. CI/CD 환경에서 환경 변수를 설정했는지 확인하세요.

정보

Cloudflare Pages, Vercel 등에서 Settings → Environment Variables에서 설정

3. TypeScript 엄격 모드

TypeScript의 엄격한 타입 체크를 임시로 완화하려면:

tsconfig.json
{
  "compilerOptions": {
    "strict": false,           // 임시 해결 (비추천)
    "noImplicitAny": false,    // any 허용
    "skipLibCheck": true       // 라이브러리 타입 체크 건너뛰기
  }
}

주의

이 방법은 임시 해결책입니다. 타입 에러는 근본적으로 해결하는 것이 좋습니다.

4. 로컬에서 빌드 테스트

배포 전에 항상 로컬에서 빌드가 성공하는지 확인하세요:

터미널
# 빌드 실행
npm run build

# 빌드 결과물로 미리보기
npm run preview

관련 문서

환경 변수 에러

process.env.XXX is undefined

SPA 404 에러

배포 후 새로고침 시 404