Vercel Cache Reason: MISS·BYPASS·STALE을 같은 캐시 문제로 보지 않는 법
테크
조회 6
캐시 상태만 보면 MISS, BYPASS, STALE은 모두 “HIT가 아니다”로 뭉개집니다. 2026년 7월 17일부터 Vercel 런타임 로그는 cacheable response가 새 HIT가 아니었던 이유를 Cache Reason으로 보여줍니다. 이제 캐시를 늘릴 문제와 의도된 우회, 재검증 장애를 서로 다른 운영 티켓으로 나눌 수 있습니다.
상태보다 이유를 함께 읽어야 하는 이유
상태는 무슨 일이 일어났는지, reason은 왜 그 경로를 탔는지 답합니다. 동적 응답은 이유가 없을 수 있고, ISR·Partial Prerendering·Cache-Control 응답처럼 CDN이 캐시할 수 있는 요청에서 reason이 특히 유용합니다.
| 상태 | 대표 reason | 운영 해석 |
|---|---|---|
| MISS | Cold · Request collapsed · Error | 캐시가 없거나 읽지 못해 원본이 생성 |
| BYPASS | Draft Mode · Prerender Bypass · Crawler | 캐시를 의도적으로 건너뜀 |
| STALE | Time-based · Tag invalidation · Revalidation error | 기존 응답을 주고 백그라운드 갱신 |
| REVALIDATED | Tag-based deletion | 기존 항목이 없어 전경에서 재생성 |
운영 체크리스트
✓MISS + Cold는 첫 요청·새 배포·지역별 축출인지 확인하고, 자주 쓰는 경로의 사전 렌더링과 수명을 검토합니다.
✓BYPASS + Draft Mode/Crawler는 의도된 우회일 수 있으므로 적중률 저하로 바로 분류하지 않습니다.
✓STALE + Revalidation error는 마지막 정상 응답이 제공되는 동안 원본 함수·데이터 소스 오류를 조사합니다.
✓vercel metrics에서 cache_reason으로 그룹화해 단일 요청 디버깅을 트래픽 비율로 확장합니다.
결론
운영 목표는 HIT 비율 하나를 최대화하는 것이 아닙니다. reason별로 사용자 지연, 원본 부하, 최신성, 장애 은닉 위험을 나눠 측정해야 합니다.