排查Nginx缓存失效是否由配置冲突引起，核心是验证“本该缓存的请求为何没进缓存”：通过add_header X-Cache-Status $upstream_cache_status;查看响应头状态，结合access_log中$upstream_cache_status日志、缓存目录文件数量及减法测试定位proxy_cache_valid覆盖缺失、proxy_ignore_headers误用、cache_key与bypass矛盾、location作用域错位等典型冲突。
排查 Nginx 缓存失效是否由配置冲突引起，核心是验证“本该缓存的请求为何没进缓存”，而不是泛泛检查语法或重启服务。真正卡点往往藏在多层指令相互覆盖、作用域错位或响应头被误判中。
看真实缓存状态，别信配置文件
配置写了不等于生效，必须通过运行时信号确认：
- 在对应
location块中加add_header X-Cache-Status $upstream_cache_status;，再用curl -I查响应头，看到X-Cache-Status: MISS或BYPASS才算真实未命中 - 检查 access_log 是否启用
$upstream_cache_status变量，观察日志里大量出现EXPIRED（缓存存在但过期）还是BYPASS（被规则主动跳过）——前者指向proxy_cache_valid设置不合理，后者直指proxy_cache_bypass或请求头干扰 - 进缓存目录（如
/var/cache/nginx/）执行find . -type f | wc -l，若数量长期为 0 或突降，说明缓存根本没写入，不是失效，是压根没建起来
揪出典型配置打架场景
以下几类冲突最常导致“明明配了却失效”：
-
proxy_cache_valid 被状态码过滤掉：比如只写了
proxy_cache_valid 404 1m;，但接口实际返回 200，那这条规则完全不生效；必须确保覆盖真实响应码，例如proxy_cache_valid 200 301 302 10m; -
proxy_ignore_headers 用错了范围：若加了
proxy_ignore_headers Cache-Control;，Nginx 就彻底无视后端返回的Cache-Control: public, max-age=3600，但同时也丢掉了其中有效的public标识；更稳妥的是只忽略非法值，比如proxy_ignore_headers "Cache-Control" "Expires";配合显式proxy_cache_valid -
cache_key 和 bypass 条件矛盾：例如
proxy_cache_key "$scheme$host$request_uri $cookie_user_id";包含用户标识，但proxy_cache_bypass $cookie_user_id;却把有 cookie 的请求全绕过了——结果就是 key 有用户信息，但请求根本不会进缓存 -
location 嵌套导致作用域失效：在
server块里直接写proxy_cache_valid，而没放在具体location内，该指令会被忽略；所有缓存相关指令（proxy_cache、proxy_cache_key等）必须在location中定义才有效
验证响应头是否被污染或覆盖
后端返回的头可能和 Nginx 缓存逻辑打架，尤其当它带了禁止缓存的信号：
- 用
curl -I检查原始响应，重点看是否有Cache-Control: no-cache、Set-Cookie、Expires: -1等；这些会触发 Nginx 默认 bypass 行为 - 若后端确实要返回
Set-Cookie（如登录态），但又想缓存响应体，需加proxy_hide_header Set-Cookie;并配合proxy_ignore_headers Set-Cookie;，否则 Nginx 会因该头拒绝缓存 - 注意
add_header Cache-Control是发给客户端的，不影响 Nginx 自身缓存决策；真正控制 Nginx 缓存的是proxy_cache_valid和响应头解析结果
快速验证是否真冲突：临时最小化配置
怀疑多条指令互斥时，做一次“减法测试”：
- 注释掉所有
proxy_cache_bypass、proxy_no_cache、proxy_ignore_headers，只保留最基础缓存配置（proxy_cache+proxy_cache_valid+proxy_cache_key） - 用同一请求反复测试，观察
X-Cache-Status是否变为HIT；如果此时能命中，说明原配置中某条指令确实在静默拦截 - 逐条恢复被注释的指令，每次 reload 后验证，就能定位到哪一行引发冲突
