빌드 에러로 배포가 막혔을 때

배포 직전에 빌드 에러가 발생하면 당황하기 쉽다. 처음부터 정답을 맞히려고 하면 오히려 확인 시간이 길어진다. 체계적으로 접근하면 대부분 30분 안에 해결된다.

빌드 출력 메시지 읽기

빌드 명령을 실행하면 콘솔에 에러가 나타난다. 가장 먼저 나타나는 에러부터 읽는다.

npm run build

여러 에러가 떠도 첫 번째 에러가 원인인 경우가 많다. 그 에러를 먼저 해결하면 나머지는 자동으로 해결될 수도 있다.

파일 확인

에러 메시지에 파일명과 줄 번호가 있으면 그 파일을 직접 열어본다.

# 에러가 나는 파일 편집
vim src/pages/example.tsx:42

로컬에서는 문제가 없었다면:

• 배포 환경에서 수정되지 않은 파일이 있을 수 있다 (git에 안 커밋됨)
• 의존성 버전이 다를 수 있다 (npm install 재실행)
• 환경 변수가 없어서 타입 체크가 실패했을 수 있다

재현 조건 파악

빌드 환경과 로컬 환경의 차이를 찾아본다.

1. 의존성 버전:

npm ls | grep package-name
npm ci  # package-lock.json 기준으로 설치

2. 노드 버전:

node --version
npm --version

3. 환경 변수:

# .env 파일이 배포 환경에 있는지 확인
ls -la .env*

로컬에서 정확히 재현하기

배포 직전에 로컬에서도 같은 명령으로 빌드해본다.

# 캐시를 모두 지우고 깨끗한 상태에서
rm -rf node_modules .next dist
npm ci
npm run build

이렇게 하면 배포 환경과 동일한 상태로 테스트할 수 있다.

타입 체크와 린트

빌드 에러의 많은 부분은 실제로는 타입 체크나 린트 규칙 위반이다.

npx tsc --noEmit
npm run lint

이 두 명령이 성공하면 빌드도 대부분 성공한다.

브라우저에서 확인

빌드가 성공했다면 실제 앱이 시작되는지 확인한다.

# 로컬 서버 실행
npm start
# 또는
npm run dev

http://localhost:3000 (포트는 프로젝트마다 다름) 에서 화면이 정상 표시되는지 본다.

에러 기록

빌드 실패 상황을 기록해두면 나중에 같은 문제가 생길 때 도움이 된다:

• 정확한 에러 메시지
• 영향받는 파일들
• 시도해본 해결책
• 최종 해결책

다음번에 비슷한 에러가 나면 이 기록을 먼저 찾아보는 것만으로 시간을 크게 절약할 수 있다.