Next.js 정적 생성 배포 후 화면이 다를 때 확인 순서

Next.js로 정적 생성(Static Generation)을 사용하면 빌드 시점에 페이지가 모두 생성된다. 로컬에서는 멀쩡했는데 배포 후 화면이 다르게 보이는 건 보통 빌드 환경이 다르기 때문이다.

재현 조건 명확히 하기

먼저 어느 페이지에서 어떻게 다르게 보이는지 정확히 정리한다. 특정 경로인지 모든 페이지인지, 콘텐츠가 빠져있는지 스타일이 안 먹는 건지 구분해야 한다.

로컬 빌드 결과 확인

정적 생성은 빌드 시점의 결과물이다. 로컬에서 빌드를 실행하고 결과를 확인해본다.

npm run build

.next/standalone 또는 .next/out 디렉토리에 생성된 정적 파일들을 확인한다.

빌드 환경 변수 확인

정적 생성 중에 사용되는 환경 변수가 로컬과 배포 서버에서 다를 수 있다. .env.production을 확인하고, 배포 서버의 환경 변수 설정을 점검한다.

캐시와 CDN 설정

배포 후 브라우저나 CDN 캐시 때문에 이전 버전이 보일 수 있다. Hard refresh를 시도해본다.

curl -I https://example.com/page

Cache-Control 헤더를 확인하고, 필요하면 캐시 무효화를 한다.

설정 파일 확인

next.config.js에서 정적 생성 관련 설정(output, trailingSlash 등)을 확인한다. 로컬과 배포 환경에서 다른 설정이 적용될 수 있다.

최종 확인: 공개 URL

배포된 페이지에서 실제로 화면을 본다. 개발자 도구로 네트워크 탭을 열어서 리소스가 제대로 로드되는지 확인한다.

문제가 반복되면 빌드 과정과 배포 설정의 차이를 정리해두면 다음 배포가 훨씬 쉬워진다.