Next.js 캐싱 문제로 구 콘텐츠가 보일 때

Next.js 앱을 배포한 후 변경 사항이 반영되지 않는 일이 있다. 사용자가 브라우저 캐시 때문에 구 버전을 보는 경우도 있고, 서버 캐싱 때문일 수도 있다. 어디서 캐시되고 있는지 파악하는 게 핵심이다.

먼저 HTML head를 확인하기

캐싱 문제를 추적하려면 HTTP 헤더와 HTML 메타데이터를 봐야 한다. Cache-Control 헤더가 뭘로 설정되어 있는지, 그리고 실제 HTML 콘텐츠가 최신인지를 확인한다.

• 먼저 볼 값: HTTP Cache-Control, Last-Modified, ETag 헤더
• 같이 비교할 값: 배포 후 첫 요청과 캐시된 요청
• 기록해둘 것: 응답 헤더, 빌드 타임스탬프, 콘텐츠 해시

curl로 HTTP 헤더 확인하기

# 응답 헤더만 보기
curl -I https://example.com/page

# 헤더와 콘텐츠 확인
curl -s https://example.com/page | head -50

# 캐시 헤더 없이 요청하기 (-H "Cache-Control: no-cache")
curl -I -H "Cache-Control: no-cache" https://example.com/page

CDN 캐시 무효화

Cloudflare 같은 CDN을 쓰면 엣지 서버에 캐시되는데, 이게 배포 후에도 계속 구 버전을 제공할 수 있다. CDN 관리 콘솔에서 캐시를 지워야 한다.

Next.js 빌드 결과물 확인

배포하기 전에 빌드 결과가 실제로 새로 생성되었는지 확인한다. .next 디렉토리의 타임스탬프를 보거나, 빌드 로그에서 어떤 파일들이 생성되었는지 본다.

# 빌드 실행
npm run build

# .next 디렉토리의 최신 파일 확인
ls -ltr .next/static/chunks/ | tail -10

배포 후 서버 재시작

때론 애플리케이션 프로세스가 여전히 구 버전을 메모리에 들고 있을 수 있다. 배포 후에는 명시적으로 서버를 재시작하거나, 프로세스를 재로드한다.

사용자 캐시도 고려하기

서버 쪽은 모두 확인했는데도 사용자가 구 버전을 보는 경우가 있다. 이럴 땐 브라우저의 캐시 정책을 조정해야 한다. JavaScript나 CSS 파일 URL에 버전 해시를 포함해서 브라우저가 새로 다운로드하도록 강제한다.

# Next.js에서 자동 해시 추가됨
# _app.js -> _app.29f8a3b1.js (해시 포함)

캐싱 문제는 여러 레이어에서 동시에 일어나기 때문에, 먼저 각 계층을 분리해서 생각해야 한다. CDN 캐시, 서버 캐시, 브라우저 캐시 중 어디에 문제가 있는지 파악하면 해결 방법도 명확해진다.