Next.js가 로컬에서만 되고 서버에서 터질 때 확인하기

Next.js 프로젝트가 로컬에서는 완벽하게 작동하는데 서버에 배포하면 에러가 난다면, 문제는 SSR(Server-Side Rendering) 중에 발생했을 가능성이 높다. 로컬의 npm run dev는 개발 모드이고, 배포는 프로덕션 빌드라서 동작이 다를 수 있다.

문제의 경계 파악

에러가 정확히 언제 나는가. 페이지 로드 시점에 나는가, 데이터 페칭 중에 나는가. 특정 라우트에서만 나는가.

로컬과 운영 비교

로컬에서 프로덕션 빌드를 해서 테스트한다. next build 후 next start로 실행하면 배포 환경과 유사한 조건에서 테스트할 수 있다.

curl -s https://example.com | grep -Ei 'title|description|canonical|og:|twitter:'
npm run build

배포된 서버에서 실제 HTML을 확인한다. 메타데이터가 제대로 서버에서 생성되는지, 아니면 클라이언트에서만 생성되는지 본다.

canonical과 메타데이터 설정

SSR 중에 메타데이터가 생성되지 못했다면, generateMetadata 함수가 제대로 실행되는지 확인한다. 데이터 페칭이 실패하면 메타데이터도 생성 못 한다.

응답 확인

API 요청이 배포 환경에서 실패하는 건 아닌지 본다. URL이 다른가, 권한이 없는가, 타임아웃이 나는가.

빌드 로그 확인

빌드 중에 경고나 에러가 없었는지 확인한다. 동적 라우팅 관련 메시지나 빌드 최적화 관련 정보를 본다.

위험한 수정

한 번에 여러 파일을 수정하면 뭐가 원인인지 알 수 없다. 작은 부분부터 수정하고 배포한 후 다시 테스트한다.

체크리스트

수정 후 다음을 확인한다:

• 같은 증상이 다시 나오는가
• 로그나 응답에서 바뀐 부분이 있는가
• 공개 URL에서 제대로 작동하는가

마지막으로, 한 번에 한 가지 설정만 바꿔도 원인 추적이 훨씬 쉬워진다. 다음에 비슷한 문제가 생길 때를 대비해 이번에 무엇이 원인이었는지 기록해둔다.