查看Nginx proxy_cache命中状态的核心是通过add_header X-Cache-Status $upstream_cache_status将内置变量输出至响应头，配合HIT/MISS/EXPIRED等值直观判断缓存行为，并需确保后端响应头、proxy_cache_valid、绕过规则及缓存键配置正确以避免误判。
要查看 Nginx proxy_cache 的命中状态，核心是使用内置变量 $upstream_cache_status，它会在响应头中输出缓存行为（如 HIT、MISS、EXPIRED 等），无需额外模块或日志解析。
在响应头中直接查看缓存状态
最简单有效的方式是让 Nginx 将该变量作为响应头返回，方便用浏览器开发者工具或 curl 查看：
- 在
location或server块中添加：
add_header X-Cache-Status $upstream_cache_status; - 重启或重载 Nginx（
nginx -s reload） - 发起请求，例如：
curl -I https://your-domain.com/test.html
响应头中会出现类似：
X-Cache-Status: HIT
常见 $upstream_cache_status 值含义
该变量值反映本次请求与缓存的交互结果，典型取值包括：
CPA Update - Secure CLI Proxy API Maintenance
下载
安全更新和维护 CLI Proxy API（CPA）部署与配置。用于 CPA 镜像升级、配置变更、认证目录兼容修复、上线验证与回滚。适用于用户提到“CPA 更新/升级/配置改了/容器重建/回滚”等场景。
- HIT：命中本地缓存，直接返回，不转发给后端
- MISS：未命中，Nginx 向后端请求并缓存响应（首次或缓存失效后）
-
EXPIRED：缓存已过期，但 Nginx 仍返回旧内容（需配合
proxy_cache_use_stale），同时异步更新缓存 -
STALE：返回了过期缓存（因后端不可用等，启用
proxy_cache_use_stale时触发） -
BYPASS：因
proxy_cache_bypass规则跳过缓存（例如带特定 Cookie 或参数） -
REVALIDATED：使用
proxy_cache_revalidate on，验证后端未修改，复用缓存
通过 access_log 记录缓存状态
若需长期追踪或分析，可将变量写入访问日志：
- 定义自定义日志格式：
log_format cache '[$time_local] $remote_addr "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" "$upstream_cache_status" $upstream_http_x_cache; - 在
server或location中启用：
access_log /var/log/nginx/cache.log cache; - 日志示例行：
[21/Jan/2025:10:22:33 +0800] 192.168.1.100 "GET /api/data HTTP/1.1" 200 1234 "-" "curl/7.68.0" "HIT" HIT
验证缓存是否真正生效的注意事项
仅看 $upstream_cache_status 不够，还需确认以下几点避免误判：
- 后端响应必须包含允许缓存的头，如
Cache-Control: public, max-age=300（Nginx 默认只缓存 status 200/301/302，且需有有效Expires或Cache-Control） - 检查
proxy_cache_valid是否覆盖了当前响应码和缓存时间 - 确认没有被
proxy_no_cache或proxy_cache_bypass规则意外绕过 - 注意缓存键（
proxy_cache_key）是否包含易变变量（如$cookie_*、$args），导致命中率低
