에러 페이지 빌드가 서버에서만 실패할 때

로컬에서 next build는 멀쩡히 통과하는데 CI 빌드에서만 에러 페이지(404/500) 단계에서 빌드가 깨진 적이 있다. "서버에서만 실패"는 거의 환경 차이라, 빌드 로그부터 차근차근 봤다.

어느 페이지에서 깨지는지 로그로 본다

npm run build

Next.js는 빌드 중 각 페이지를 정적/동적 중 무엇으로 처리했는지 출력한다. 에러 페이지에서 멈춘다면 그 페이지가 빌드 타임에 무언가를 평가하려다 실패한 것이다. 로그의 마지막 스택을 보면 어떤 모듈에서 터졌는지 나온다.

빌드 타임에 실행되면 안 되는 코드를 찾는다

가장 흔한 원인은 에러 페이지가 빌드 시점에 window나 환경 변수, 외부 요청에 의존하는 것이었다.

• window/document 접근: 서버 빌드에는 없다. 그래서 로컬 dev에선 안 보이고 빌드에서만 터진다.
• 빌드 타임에 없는 환경 변수: CI에 그 변수를 안 넣어둔 경우.

로컬과 CI의 차이를 좁힌다

로컬은 통과하는데 CI만 실패하면, 환경 변수와 Node 버전을 먼저 맞춘다. CI에서 쓰는 것과 같은 .env로 로컬에서 npm run build를 돌리면 대개 재현된다. 재현만 되면 그다음은 빠르다. 결국 차이가 나는 변수 하나를 찾는 싸움이었다.