Next.js 캐시 문제로 로컬과 배포가 다를 때

Next.js 작업을 하다 보면 로컬에서는 잘 동작하는데 배포 후에는 다르게 보이는 일이 자주 일어난다. 특히 캐시나 메타데이터 관련 문제는 화면만 봐서는 원인을 찾기 어렵다.

무턱대고 설정을 바꾸기 전에, 먼저 공개 URL에서 실제 HTML이 어떻게 전송되는지 확인하는 게 핵심이다.

배포된 페이지에서 먼저 볼 값

공개 URL의 응답 헤더와 메타데이터를 직접 확인한다.

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

이 명령어로 실제 전송되는 meta 태그들을 본다. 브라우저에서 보는 것과 실제 HTML이 다를 수 있으니까다.

로컬 빌드와 비교하기

로컬에서도 같은 내용이 빌드되는지 확인한다.

npm run build
cat .next/server/app/page.html  # 또는 해당 페이지 경로

빌드 결과가 배포 환경과 다르면, 환경 변수나 빌드 설정에서 원인을 찾아야 한다.

캐시와 CDN 영향 확인

캐시 문제라고 의심되면 응답 헤더를 먼저 본다.

curl -I https://example.com

Cache-Control, ETag, Last-Modified 헤더를 확인한다. 필요하면 -H "Cache-Control: no-cache"를 추가해서 캐시를 우회한 응답을 본다.

확인 결과 정리하기

1. 공개 URL의 메타데이터가 맞는지 확인한다.
2. 로컬 빌드 결과와 비교한다.
3. 응답 헤더의 캐시 설정을 본다.
4. 필요하면 캐시를 무효화한다.

이 순서를 한 번 정해두면, 다음에 비슷한 문제가 나왔을 때 훨씬 빠르게 대응할 수 있다.