通过添加X-Cache-Status响应头可快速判断缓存命中状态，常见值包括HIT、MISS、BYPASS、EXPIRED、REVALIDATED；Nginx中用add_header X-Cache-Status $upstream_cache_status always配置，CDN可通过自定义响应头或边缘脚本实现，前端在DevTools Network面板查看该字段即可调试。
在前端调试中，快速判断请求是否命中 CDN 或反向代理缓存，对排查加载延迟、数据不一致等问题非常关键。通过在响应头中添加 X-Cache-Status，可以让浏览器或开发者工具直接看到缓存决策结果，无需登录服务器查日志。
明确 X-Cache-Status 的取值含义
该字段不是标准 HTTP 头，属于约定俗成的调试标识，常见值有：
- HIT：请求命中缓存（内容直接从缓存返回）
- MISS：未命中缓存（回源拉取并可能写入缓存）
-
BYPASS：被显式跳过缓存（如带
Cache-Control: no-cache或命中 bypass 规则） - EXPIRED：缓存已过期，但可能仍被服务端用作协商缓存依据（部分 CDN 支持）
- REVALIDATED：使用 If-None-Match/If-Modified-Since 协商成功，返回 304（也属广义 HIT）
Nginx 中配置 add_header 实现透传
在 Nginx 的 location 或 server 块中添加如下指令即可：
add_header X-Cache-Status $upstream_cache_status always;
注意两点：
立即学习“前端免费学习笔记（深入）”；
前端设计优化skill
下载
前端设计与 UI/UX 全方位优化专家。覆盖视觉层次、排版系统、色彩理论、响应式布局、交互体验、动画动效、无障碍访问、性能优化八大维度，帮助开发者将普通页面升级为高品质产品级界面。前端设计与 UI/UX 全方位优化专家。覆盖视觉层次、排版系统、色彩理论、响应式布局、交互体验、动画动效、无障碍访问、性能优化八大维度，帮助开发者将普通页面升级为高品质产品级界面。
-
$upstream_cache_status是 Nginx 内置变量，仅在启用proxy_cache时有效 -
always参数确保即使返回 3xx/4xx/5xx 状态码也会携带该头，便于全链路观察
若你用的是自定义缓存策略（比如基于 proxy_no_cache 或 cookie 判断），可结合 map 指令构造更精细的状态：
map $http_cookie $cache_bypass {
~*debug=nocache 1;
default 0;
}
proxy_no_cache $cache_bypass;
add_header X-Cache-Status $upstream_cache_status always;
CDN 或云服务商的等效做法
主流 CDN（如 Cloudflare、阿里云 CDN、腾讯云 CDN）通常支持自定义响应头，但不直接暴露 $upstream_cache_status。你可以：
- 在 CDN 控制台「自定义响应头」中添加
X-Cache-Status: HIT（静态值，适合简单场景） - 使用边缘脚本（如 Cloudflare Workers、阿里云 EdgeScript）动态注入：
event.respondWith(new Response(event.response, {<br> headers: new Headers({ ...event.response.headers, 'X-Cache-Status': event.response.headers.get('CF-Cache-Status') || 'MISS' })<br>})); - 部分平台（如腾讯云 CDN）原生支持
X-Cache头，值为HIT/MISS，可直接使用或重写为X-Cache-Status
前端调试时如何查看和利用
打开浏览器 DevTools → Network 标签页 → 点击某个请求 → Headers → Response Headers，查找 X-Cache-Status 即可。
进阶技巧：
- 在 Console 中执行
fetch('/api/data').then(r => r.headers.get('X-Cache-Status')).then(console.log)快速验证 - 配合条件断点：在 Network 面板右键某请求 → “Break on” → “Response Header” → 输入
X-Cache-Status，命中 MISS 时自动暂停 - 写个简易 Chrome 插件，在地址栏旁显示当前页面主资源的缓存状态（读取
performance.getEntriesByType('navigation')[0].serverTiming或发起 HEAD 请求）
