실제 서비스에서 빌드 실패가 나올 때

빌드 실패의 주요 원인들

운영 환경에서 빌드가 실패하면 배포는 당연히 안 되고 사용자 서비스가 중단된다. 내가 경험한 빌드 실패의 주요 원인:

• 타입 에러 (TypeScript)
• 의존성 버전 충돌
• 환경 변수 누락
• 로컬에서만 통과하는 설정

빌드 로그 읽기

npm run build 2>&1 | tee build.log

로그의 마지막 부분부터 거슬러 올라가며 읽는다. 에러 메시지 바로 위에 진짜 원인이 있는 경우가 많다.

"Cannot find module 'xyz'" 같은 에러면 node_modules 설치 상태를 확인한다. 로컬에서는 이미 설치되어 있어서 놓치기 쉽다.

권한과 시간대 확인

런타임 환경(서버, 컨테이너)의 권한을 확인한다:

# 빌드 프로세스가 실행되는 사용자
whoami

# 현재 시간대 (타임스탐프 기반 캐시가 있으면 중요)
date

# 디스크 여유 공간
df -h

빌드 과정에서 대량의 임시 파일이 생기므로 디스크가 가득 차있으면 실패한다.

배포 환경과 로컬의 차이를 최소화

로컬에서는 통과하는데 배포 환경에서만 실패하는 경우가 있다. 이는 Node 버전, npm 버전, 환경 변수 차이 때문이다.

# 동일 환경 재현
node --version
npm --version

# 의존성 깔끔하게 재설치
rm -rf node_modules package-lock.json
npm install
npm run build

한 가지씩만 수정하기

빌드 성공 후 기록을 남긴다:

• 언제 수정했는가
• 어떤 파일을 수정했는가
• 오류 메시지가 정확히 무엇이었는가

다음에 유사한 오류가 나면 지난 기록을 보고 빠르게 대처할 수 있다. 특히 팀으로 개발할 때 이런 기록이 매우 유용하다.