需在启用缓存的 location 块中用 add_header X-Cache-Status $upstream_cache_status; 输出缓存状态，确保已配置 proxy_cache、proxy_cache_valid 等指令且请求实际走缓存，变量不可用于 if 块或 server/http 顶层。
要在 Nginx 响应头中暴露 $upstream_cache_status（即缓存命中状态，如 HIT、MISS、EXPIRED 等），需使用 add_header 指令，并确保该变量在响应阶段可被访问——关键在于：它只能在 location 或更内层作用域中使用，且不能放在 if 块或某些不支持变量扩展的上下文中。
确认已启用代理缓存并定义了 cache_zone
只有配置了有效的 proxy_cache（如 proxy_cache my_cache;）且请求实际经过缓存处理，$upstream_cache_status 才会有值。未启用缓存或请求被 bypass（如带 Cookie、禁用缓存头），该变量始终为空或 BYPASS。
- 检查是否有
proxy_cache_path定义缓存路径和 zone 名称 - 对应 location 中必须有
proxy_cache+proxy_cache_valid等指令 - 避免
proxy_cache_bypass或proxy_no_cache无条件绕过缓存
在 location 块中使用 add_header 正确输出
add_header 支持变量插值，但仅限于响应头生成阶段可用的变量。$upstream_cache_status 属于“上游响应后”变量，必须放在 location 内，且推荐放在 proxy_pass 后面（Nginx 会按执行顺序解析）：
location / {
proxy_pass http://backend;
proxy_cache my_cache;
proxy_cache_valid 200 10m;
proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504;
<pre class="brush:php;toolbar:false;"># ✅ 正确：在 location 中直接添加，变量可正常展开
add_header X-Cache-Status $upstream_cache_status;}
- 不要写成
add_header X-Cache-Status "$upstream_cache_status"（引号非必需，反而可能引发空格问题） - 避免放在
server或http块顶层——此时变量不可用，将输出空字符串 - 若需对所有响应统一加头，仍需在每个启用缓存的
location中单独配置
注意响应头继承与覆盖行为
add_header 默认不继承父块，且同名 header 会覆盖而非追加。如果上游服务本身返回了 X-Cache-Status，Nginx 的 add_header 会将其替换为自己的值（这是预期行为）。
- 如需保留原始 header 并额外添加，改用
proxy_hide_header防止透传上游同名头 - 若想调试，可同时添加：
add_header X-Upstream-Cache $upstream_cache_status;和add_header X-Upstream-Addr $upstream_addr;辅助定位 - 浏览器开发者工具 Network 标签页 → Response Headers 中查看是否出现该字段
验证是否生效的简单方法
重启 Nginx 后发起两次相同请求（如 curl -I https://example.com/），观察响应头变化：
- 首次请求：应看到
X-Cache-Status: MISS或MISS - 第二次请求（未过期）：应变为
X-Cache-Status: HIT - 若始终为空，检查 access.log 中
$upstream_cache_status是否记录了值（如log_format main ... $upstream_cache_status）
