빌드가 실패하면 가장 먼저 무엇을 확인해야 하나요?

에러 로그의 파일 경로와 라인 번호를 먼저 확인하고, 타입 오류인지 의존성 문제인지 원인 범주를 구분해야 합니다.

Module not found 에러는 어떻게 해결하나요?

누락된 패키지를 설치하고 import 경로를 점검한 뒤 lockfile 상태에서 npm install 또는 npm ci를 다시 실행합니다.

빌드 실패 해결하기

자주 발생하는 빌드 에러

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

빌드 실패 해결하기

Error: Command "npm run build" exited with 1

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

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

자주 발생하는 빌드 에러

1. 의존성 문제

2. 환경 변수 누락

3. TypeScript 엄격 모드

4. 로컬에서 빌드 테스트

Prerequisites

Validation

Troubleshooting

References

관련 문서

환경 변수 에러

SPA 404 에러

피드백 보내기