Next.js 배포 후 캐시 때문에 오래된 콘텐츠가 보일 때

Next.js 앱을 배포한 후 HTML이나 CSS가 업데이트되지 않고 이전 버전이 계속 보이는 경우가 있다. 이는 브라우저 캐시, CDN 캐시, 또는 서버 캐시 정책이 잘못되었을 때 발생한다.

브라우저 캐시 먼저 확인하기

먼저 개발자 도구에서 "캐시 무시" 옵션을 켜고 다시 로드한다. 그러면 브라우저 캐시를 무시하고 새로운 파일을 가져온다.

개발자 도구 > Network 탭 > "캐시 비활성화" 체크박스 활성화 > F5 새로고침

만약 이 상태에서 새 콘텐츠가 보인다면 순수 브라우저 캐시 문제다. 사용자들에게 캐시를 지우라고 말하거나, 서버 응답 헤더를 수정해야 한다.

HTTP 캐시 헤더 설정

Next.js는 정적 파일과 동적 페이지마다 다른 캐시 전략을 써야 한다.

// next.config.js
module.exports = {
  headers: async () => [
    {
      source: '/public/:path*',
      headers: [
        {
          key: 'Cache-Control',
          value: 'public, max-age=31536000, immutable', // 1년
        },
      ],
    },
    {
      source: '/:path*',
      headers: [
        {
          key: 'Cache-Control',
          value: 'public, max-age=3600, s-maxage=3600', // 1시간
        },
      ],
    },
  ],
};

정적 번들 파일(.next/static의 JS, CSS)은 파일명에 해시가 포함되므로 오래 캐시해도 안전하다. 하지만 HTML 페이지는 짧게 캐시해야 새 버전을 빠르게 반영할 수 있다.

파일 버전 관리

Next.js는 빌드할 때마다 정적 파일에 다른 해시를 붙인다. 이를 활용해서 캐시를 우회할 수 있다.

# 빌드 후 생성된 파일들
ls -la .next/static/chunks/
# 예: main-a1b2c3d4.js, main-e5f6g7h8.js (해시가 다름)

파일 이름이 바뀌었다는 것은 캐시가 무효화되었다는 의미다. 만약 배포 후에도 파일명이 같다면 빌드가 제대로 되지 않은 것이다.

CDN 캐시 무효화

Cloudflare, AWS CloudFront 같은 CDN을 사용한다면 배포 후 캐시를 비워야 한다.

# Cloudflare API로 캐시 비우기
curl -X POST "https://api.cloudflare.com/client/v4/zones/{zone_id}/purge_cache" \
  -H "Authorization: Bearer {token}" \
  -d '{"purge_everything": true}'

배포 시간 기록하기

ISR(Incremental Static Regeneration)을 사용한다면 재검증 시간을 확인한다.

// pages/index.js
export async function getStaticProps() {
  return {
    props: { /* 데이터 */ },
    revalidate: 300, // 5분마다 재검증
  };
}

ISR 페이지는 배포 직후에도 이전 캐시를 잠깐 보여줄 수 있다. 이는 의도된 동작이지만, 중요한 업데이트라면 설정을 조정해야 한다.

체크리스트

1. 브라우저 개발자 도구에서 캐시를 무시하고 새로고침한다.
2. HTTP 응답 헤더의 Cache-Control 값을 확인한다.
3. 정적 파일의 해시가 배포마다 바뀌는지 확인한다.
4. CDN을 사용한다면 캐시를 비운다.
5. ISR 페이지의 재검증 시간을 확인한다.
6. 배포 로그에서 빌드가 완료되었는지 확인한다.

캐시 문제는 다양한 계층에서 발생한다. 브라우저, 서버, CDN 순으로 체계적으로 확인하면 대부분 해결할 수 있다.