배포 후 페이지 캐시 문제 해결하기

캐시가 만드는 문제들

배포 후 사용자들이 "이전 페이지가 계속 보여요"라고 신고하면 캐시 문제일 가능성이 높다. Nginx, CDN, 브라우저 캐시 등 여러 계층에서 캐싱이 일어나는데, 각 계층을 제대로 이해하지 못하면 배포해도 변경사항이 반영되지 않는다.

또한 프로덕션 빌드가 너무 크거나 정적 파일이 많으면 페이지 로드 속도가 느려질 수 있다.

Nginx 캐시 확인

Nginx에서 정적 파일 캐시 헤더를 설정했다면, 이게 너무 길지 않은지 확인해야 한다.

curl -I https://example.com/static/app.js | grep -i cache

출력 예:

Cache-Control: public, max-age=31536000
ETag: "abc123"

max-age=31536000은 1년인데, 이 정도면 적절하다. 하지만 HTML 파일은 캐시하면 안 된다.

# Nginx 설정 (nginx.conf)
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2)$ {
  expires 1y;
  add_header Cache-Control "public, immutable";
}

location ~ \.html$ {
  add_header Cache-Control "no-cache, no-store, must-revalidate";
}

브라우저 캐시 무효화

파일 이름에 해시를 붙여서 브라우저가 새 파일인 줄 알도록 한다. 보통 번들러가 자동으로 해준다.

<!-- 이전 (캐시됨) -->
<script src="/app.js"></script>

<!-- 배포 후 (새 파일로 인식) -->
<script src="/app.a1b2c3d4.js"></script>

Next.js나 Webpack을 쓰면 기본적으로 해시 기반 파일명을 생성한다.

빌드 크기 확인

배포한 파일이 너무 크면 다운로드 시간이 길어진다.

npm run build
ls -lh out/  # 또는 .next/

# 또는 번들 분석 도구 사용
npm run analyze  # webpack-bundle-analyzer 설치 필요

큰 라이브러리를 찾아서 제거하거나, 동적 import로 분할한다.

// 동적 import로 분할
const HeavyComponent = dynamic(
  () => import('./HeavyComponent'),
  { loading: () => <div>로딩중...</div> }
);

CDN 캐시 초기화

Cloudflare 같은 CDN을 쓴다면 배포 후 캐시를 초기화해야 한다.

# Cloudflare API로 캐시 초기화
curl -X POST "https://api.cloudflare.com/client/v4/zones/{zone_id}/purge_cache"   -H "Authorization: Bearer {token}"   -H "Content-Type: application/json"   --data '{"files": ["https://example.com/index.html"]}'

또는 대시보드에서 "Purge Cache" → "Purge Everything"을 클릭한다.

배포 전 체크리스트

• 정적 파일(js, css)에 적절한 캐시 헤더를 설정했는가?
• HTML은 캐시하지 않도록 설정했는가?
• 번들 크기를 확인했는가? (통상 메인 번들 < 200KB)
• 큰 라이브러리는 동적 import로 분할했는가?
• CDN을 쓰는 경우 배포 후 캐시 초기화를 할 계획이 있는가?
• 개발자 도구에서 캐시를 비웠을 때와 비우지 않았을 때 모두 테스트했는가?

이 항목들을 확인하면 배포 후 캐시 관련 문제를 대부분 방지할 수 있다.