必须在启用 proxy_cache 的 location 块中配置 add_header X-Cache-Status $upstream_cache_status always，确保所有响应（含304/4xx/5xx）均携带缓存状态，值如HIT、MISS、BYPASS等反映真实缓存行为。
直接在 Nginx 的 location 块中配置 add_header X-Cache-Status $upstream_cache_status always;，就能让每次响应都带上缓存状态，前端通过浏览器开发者工具或脚本即可实时读取，无需改后端逻辑。
必须放在 location 块里，不能写在 if 或 server 根层级
这个 header 必须嵌套在启用了缓存的 location 中，且不能包裹在 if、map 或未匹配的条件块内——否则变量 $upstream_cache_status 会为空，导致头缺失或值为“-”。
- ✅ 正确：在启用
proxy_cache的 location 内直接写 - ❌ 错误：写在
server块顶层，或套在if ($args ~* "debug") { ... }里 - ⚠️ 注意：若同时用
fastcgi_cache（如 PHP-FPM 场景），应换用$fastcgi_cache_status
加上 always 参数，确保 304/4xx 等非 200 响应也能输出
默认情况下，Nginx 只对成功响应（如 200）添加自定义 header；加 always 后，即使返回 304 Not Modified、404 或 502，X-Cache-Status 依然可见，这对调试缓存行为非常关键。
- 比如：带
If-Modified-Since的请求返回 304，仍能看到是 HIT 还是 BYPASS - 再如：后端挂了返回 502，若配置了
proxy_cache_use_stale error，可能看到 STALE
前端怎么查看和简单利用这个字段
打开浏览器 DevTools → Network → 点击任意请求 → Headers → Response Headers，找到 X-Cache-Status 即可。常见值含义如下：
立即学习“前端免费学习笔记（深入）”；
- HIT：缓存命中，Nginx 直接返回本地副本，未连后端
- MISS：首次访问或缓存失效，Nginx 回源拉取并写入缓存
-
BYPASS：因
proxy_cache_bypass规则（如含no-cache头或特定 cookie）跳过缓存 - EXPIRED：缓存存在但已过期，Nginx 返回旧内容的同时异步刷新
-
STALE：后端不可用，Nginx 按
proxy_cache_use_stale返回过期缓存
验证是否生效的两个快捷方式
改完配置别急着上线，先本地确认：
- 用
curl -I http://localhost/path查看响应头，确认有X-Cache-Status: HIT类字段 - 连续发两次相同请求：第一次通常是
MISS，第二次应为HIT（前提是缓存规则允许且没被 bypass） - 若始终是
BYPASS，检查请求是否携带Cache-Control: no-cache或设置了proxy_cache_bypass $cookie_nocache且 cookie 存在
