배포 전에 정적 페이지 생성이 실패했을 때

배포하려는 순간 빌드가 실패하거나 정적 페이지 생성에 문제가 생기면 당황스럽다. 로컬에서는 괜찮았는데 배포 환경에서는 다르게 작동하는 경우가 이것이다.

처음 보이는 증상 확인

빌드 로그에서 어느 페이지, 어느 단계에서 실패했는지 본다. "전체 빌드 실패"라는 메시지보다는 구체적인 페이지 경로와 에러 메시지를 찾아야 한다.

원인을 두 가지로 나누기

실패한 페이지는 정적 생성 중에 뭔가 값을 읽으려고 했는가. 또는 빌드 단계에서 환경 변수가 제대로 로드되지 않았는가를 확인한다. 페이지가 특정 환경 변수에 의존하는가도 중요하다.

빌드 로그 직접 보기

npm run build

로컬에서 배포 환경과 같은 명령으로 빌드한다. 로컬에서도 같은 에러가 나는가, 아니면 배포 환경에서만 나는가에 따라 다음 단계가 달라진다.

배포 환경의 설정 확인

로컬과 배포 환경의 환경 변수가 정말 같은가. 데이터베이스 연결 문자열, API 엔드포인트, 권한 등을 확인한다. 정적 생성은 빌드 시점에 일어나므로, 배포 환경의 설정이 그 시점에 제대로 로드되어야 한다.

수정 후 재배포 전 체크

로컬에서 수정 후 빌드가 성공했다고 해서 바로 배포하지 말고, 실제 배포 환경에서의 조건을 최대한 재현해본다. 실제 화면, 빌드 결과, 정적 페이지 생성 결과를 모두 확인한 후 배포한다. 이렇게 하면 다음 번에 비슷한 문제가 나올 때 훨씬 빨리 해결할 수 있다.