Next.js 캐시가 먹지 않을 때

Next.js에서 캐시 문제는 보통 빌드 시점의 환경변수, 메타 태그 생성, CDN 캐시가 복합적으로 작용한다. 화면만 보고 판단하면 놓치는 부분이 많다.

먼저 실제 HTML을 확인하기

브라우저에서 Ctrl+U로 페이지 소스를 보고 메타 태그를 직접 확인한다. canonical, og: 태그, description 등이 제대로 있는지, 값이 맞는지 본다.

# curl로 실제 서버가 내려주는 HTML 확인
curl -s https://example.com | grep -Ei 'title|description|canonical|og:|twitter:'

빌드 시점의 환경변수

Next.js는 빌드할 때 환경변수를 읽는다. .env.local 파일이 있는지, 필요한 변수가 설정돼 있는지 확인한다. 특히 배포 파이프라인에서 환경변수를 빌드 시에 전달해야 한다.

# 빌드 시 환경변수 확인
npm run build
# 빌드 로그에서 환경 관련 메시지 확인

메타 태그가 동적으로 생성되는가

일부 메타 태그는 빌드 후 요청 시점에 생성된다. 이런 경우 서버의 응답이 제대로 생성되는지 확인해야 한다. 특히 SEO 메타 태그는 검색 엔진이 정확히 읽을 수 있어야 한다.

CDN 캐시 무효화

이미 배포된 페이지를 수정했다면 CDN이나 브라우저 캐시 때문에 새 내용이 안 보일 수 있다. 캐시 헤더를 확인하고, 필요하면 강제 무효화한다.

# 응답 헤더에서 캐시 정책 확인
curl -I https://example.com

로컬과 배포 환경의 차이

로컬에서는 핫 리로드 때문에 항상 최신 내용을 볼 수 있지만, 배포 후에는 빌드된 정적 파일을 서빙한다. 배포 후 시간이 지나서 문제를 발견했다면 빌드 당시 환경과 지금이 다를 수 있다.

확인 체크리스트

메타 태그가 제대로 작동하는지 확인:

1. 실제 HTML 소스 확인 (개발자도구, curl)
2. 빌드 시점의 환경변수 기록
3. CDN 캐시 상태
4. 배포 후 실제 페이지 접근해서 확인

이 기록을 남겨두면 다음에 SEO나 메타 태그 관련 문제를 빠르게 해결할 수 있다.