可在nginx中用add_header指令配合$upstream_cache_status变量在响应头添加缓存状态(如hit、miss、expired等),需先启用proxy_cache并配置缓存区与策略,且add_header需加always参数才支持非2xx/304响应。

可以在 Nginx 中使用 add_header 指令配合内置变量 $upstream_cache_status,在响应头中添加缓存命中状态(如 HIT、MIS、MISS、EXPIRED 等),便于调试和监控缓存行为。
确认已启用代理缓存
只有配置了 proxy_cache 并实际启用缓存逻辑后,$upstream_cache_status 才会有有效值。确保已在 http 或 server 块中定义缓存区,并在 location 中调用:
proxy_cache my_cache;proxy_cache_valid 200 302 10m;proxy_pass http://backend;
使用 add_header 输出缓存状态
在对应 location 块中添加如下指令:
add_header X-Cache-Status $upstream_cache_status;
注意:add_header 默认只在成功响应(2xx)和 304 响应中生效;若需在其他状态码(如 502)也输出,需加上 always 参数:
add_header X-Cache-Status $upstream_cache_status always;
常见状态值含义
$upstream_cache_status 的典型取值包括:
- HIT:请求命中本地缓存,直接返回
- MISS:缓存未命中,向后端发起新请求
-
EXPIRED:缓存存在但已过期,仍向后端验证(如带
If-Modified-Since) -
STALE:返回过期缓存(因配置了
proxy_cache_use_stale) -
BYPASS:因
proxy_cache_bypass规则跳过缓存 - REVALIDATED:缓存过期后经后端验证仍有效(304)
验证是否生效
重启 Nginx 后,用 curl 请求并查看响应头:
curl -I https://example.com/test.html
若配置正确,响应中会出现类似:
X-Cache-Status: HIT
多次请求可对比 HIT 与 MISS 的变化,确认缓存机制正常工作。











