브라우저 캐시가 Next.js 수정을 숨기고 있을 때 확인하는 법

Next.js 개발을 하다 보면 분명히 코드를 수정했는데 브라우저에서 이전 화면 그대로인 경우가 생긴다. 이게 내 코드가 반영 안 된 건지, 빌드가 잘못된 건지, 아니면 단순히 캐시 문제인지 구분하는 데 시간을 쓰게 된다.

먼저 캐시 여부부터 확인한다

가장 먼저 할 일은 브라우저 캐시를 배제하는 것이다. DevTools(F12)를 열고 Network 탭에서 "Disable cache"를 체크한 상태로 새로고침하거나, Ctrl+Shift+R(Mac은 Cmd+Shift+R)로 하드 리프레시를 한다.

이걸로 바뀌면 순수 브라우저 캐시 문제다. 안 바뀐다면 다음 단계로 넘어가야 한다.

운영 배포라면 CDN 캐시가 원인일 수 있다

Vercel이나 Cloudflare 같은 CDN을 쓰는 경우 응답 헤더를 먼저 본다.

curl -I https://example.com/

Cache-Control, Age, CF-Cache-Status 같은 헤더를 보면 CDN이 응답을 캐시하고 있는지 알 수 있다. Age: 3600이면 CDN이 1시간 된 캐시를 주고 있는 것이다.

Next.js에서 revalidate 설정이 길게 잡혀 있거나, 특정 경로에 Cache-Control: public, max-age=31536000이 붙어 있으면 배포해도 CDN이 오래된 응답을 계속 줄 수 있다.

빌드 결과 자체를 의심할 때

로컬 개발 서버(npm run dev)에서는 반영되는데 빌드 후에만 이상하다면 .next 캐시가 오염됐을 가능성이 있다.

rm -rf .next
npm run build
npm run start

.next 폴더를 지우고 다시 빌드하면 대부분 해결된다. CI 환경에서 반복적으로 발생한다면 빌드 캐시 설정을 확인해야 한다.

로컬에서 캐시 관련 동작 확인

개발 서버에서 특정 페이지가 계속 이전 내용을 보여준다면 Next.js의 라우터 캐시(Router Cache)가 원인일 수 있다. App Router에서는 클라이언트 사이드 캐시가 기본으로 활성화돼 있어서 같은 경로를 재방문해도 서버 요청을 보내지 않는 경우가 있다.

// 특정 세그먼트에서 캐시를 비활성화하려면
export const dynamic = 'force-dynamic'

또는 router.refresh()를 호출해서 현재 경로를 강제로 다시 불러올 수 있다.

확인 순서 요약

1. 브라우저 하드 리프레시 → 바뀌면 브라우저 캐시 문제
2. curl -I로 응답 헤더 확인 → CDN 캐시 여부 판단
3. .next 삭제 후 재빌드 → 빌드 캐시 오염 해결
4. dynamic = 'force-dynamic' 또는 router.refresh() → App Router 라우터 캐시 우회

단계별로 하나씩 확인하면 캐시가 어느 레이어에서 걸리는지 금방 좁혀진다.