排查 nginx proxy_cache 缓存异常,核心在于确认请求是否命中了缓存、命中的是哪个缓存文件以及为何被判定为未命中。通过开启 proxy_cache_debug on; 并检查响应头中的 x-cache-status,可以直观地看到缓存状态(hit/miss)及具体原因。

如何查看当前请求的缓存命中状态
最直接的方法是启用调试日志并观察响应头。在 location 块中设置 add_header X-Cache-Status $upstream_cache_status;,然后使用 curl -I 发送请求,返回的 X-Cache-Status 字段即为结果。若值为 HIT 表示命中,MISS 表示未命中,BYPASS 表示绕过缓存。

server {
listen 80;
server_name example.com;
proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=my_cache:10m max_size=1g inactive=60m use_temp_path=off;
location /api/ {
proxy_pass http://backend;
proxy_cache my_cache;
proxy_cache_valid 200 302 10m;
proxy_cache_valid 404 1m;
add_header X-Cache-Status $upstream_cache_status;
proxy_cache_key $scheme$request_method$host$request_uri;
}
}
执行 curl -I http://example.com/api/test,观察输出:
- 首次请求:HTTP/1.1 200 OK, X-Cache-Status: MISS
- 再次请求:HTTP/1.1 200 OK, X-Cache-Status: HIT
为什么某些请求总是显示 MISS
如果预期应命中的请求却返回 MISS,通常是因为缓存键(Cache Key)不同或缓存过期策略限制。默认情况下,Nginx 仅缓存 HTTP 200 和 302 响应,且 proxy_cache_valid 需明确配置。此外,若请求包含 Cookie 或 Authorization 头,而 proxy_cache_bypass 或 proxy_no_cache 被触发,也会导致跳过缓存。

# 检查缓存键是否一致 # 确保没有动态参数导致 URI 变化 # 检查是否有 Cookie 导致 bypass # 示例:强制忽略 Cookie 进行缓存 proxy_cache_bypass $http_cookie; proxy_no_cache $http_cookie; # 或者,如果希望基于 Cookie 区分缓存 # proxy_cache_key "$scheme$request_method$host$request_uri$http_cookie";
常见原因包括:
1. proxy_cache_valid 未覆盖特定状态码(如 500)。
2. 请求 URI 中包含时间戳或随机数,导致 $request_uri 变化。
3. 客户端发送了 Cache-Control: no-cache,且未配置 proxy_cache_revalidate 或 proxy_cache_min_uses 处理。
4. 磁盘空间不足或权限问题导致写入失败,但 Nginx 仍认为未命中。
如何验证缓存文件是否实际生成
当怀疑缓存未写入磁盘时,可直接检查 proxy_cache_path 指定的目录。例如,若配置为 /var/cache/nginx,则在该目录下查找以缓存键哈希命名的子目录和文件。同时,可通过 proxy_cache_use_stale 配置在缓存失效或后端错误时提供旧缓存,以验证缓存内容的存在性。
# 手动检查缓存目录结构 ls -lR /var/cache/nginx/my_cache/ # 示例:在缓存失效时提供旧版本 proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504; # 示例:强制刷新缓存(删除对应文件后重试) rm -rf /var/cache/nginx/my_cache/* # 重新发起请求,观察是否重新生成
若目录为空或文件不存在,说明缓存未生效。此时需检查:
- proxy_cache_path 路径是否存在且 Nginx 用户有写权限。
- use_temp_path=off 是否导致临时文件无法正确重命名。
- 后端响应头是否包含 Cache-Control: no-store 或 private,这会阻止 Nginx 缓存。











