Next.js 캐시 때문에 로컬과 서버 결과가 다를 때

Next.js로 개발할 때 가장 답답한 순간은 로컬에서 완벽한데 배포 후 SEO 관련 메타 정보가 달라지는 것이다. canonical 태그가 빠졌거나, OG 이미지가 다르거나, 페이지 제목이 잘못 나타난다.

먼저 실제 HTML을 확인하기

배포 후 바로 curl로 응답을 본다.

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

이 명령이 당신이 기대한 값을 보여주는가? 아니라면 캐시든 빌드든 문제가 있는 것이다.

로컬 빌드 결과 확인하기

Next.js는 빌드 단계에서 static generation이나 revalidation을 처리한다. 로컬에서 빌드했을 때 어떤 파일이 생성되었는지 본다.

npm run build

그리고 .next 폴더의 static 파일들을 확인한다. 실제 배포되는 HTML이 여기에 있다.

공개 URL의 응답 시간과 캐시 헤더

응답 헤더도 중요하다. 캐시 설정이 너무 길면 업데이트가 반영되지 않는다.

curl -I https://example.com

Cache-Control, ETag, Last-Modified 헤더를 확인한다. 이 값이 로컬과 다르면 배포 환경의 서버 설정이 다른 것일 수 있다.

빌드 환경 변수 다시 확인하기

배포 환경의 환경 변수가 로컬과 다를 수 있다. API 엔드포인트, CDN URL, 사이트 도메인 등이 달라지면 메타 태그도 달라진다.

빌드 후에는 로그와 응답만으로는 부족하다. 결과가 예상과 다른 이유를 설명할 수 있을 때까지 계속 확인해야 한다. 한 가지 변수만 고쳐보고 다시 빌드, 배포, 확인하는 순환을 반복한다.

배포 후 핸들링

마지막으로 실제 공개 페이지가 제대로 표시되는지, 검색 엔진이 크롤링할 때도 메타 정보가 맞는지 최종 확인한다. 이것으로 작업이 끝난다.