缓存未生效往往因配置未加载、路径权限不足、key设计不当或响应头干扰；需依次验证nginx -t语法、proxy_cache_path权限、proxy_cache_key稳定性、proxy_cache_valid覆盖状态码及X-Cache-Status响应头。
缓存未生效，往往不是“没配”，而是某个环节断开了——从配置加载、路径权限、key 设计到响应头干预，缺一不可。先确认缓存是否真被启用，再逐层验证是否命中。
第一步：确认 Nginx 是否加载了缓存配置
很多问题根本不在缓存逻辑，而在配置压根没生效：
- 运行 nginx -t 检查语法；若报
unknown directive "proxy_cahce"或directive is not allowed here，说明拼写错误（如cahe/kry/vaild）或指令位置非法 - 执行 nginx -T 输出当前实际生效的完整配置，搜索
proxy_cache_path和你定义的keys_zone名称（如mycache），看对应块是否存在；若整段消失，说明上级 block 存在语法错误导致解析提前终止 - 检查 error.log（如
/var/log/nginx/error.log），查找proxy_cache_path相关警告，例如could not build the keys_zone或open() ... failed (13: Permission denied)
第二步：验证缓存路径与权限是否就绪
缓存依赖两个目录：主缓存区（proxy_cache_path）和临时体写入区（proxy_temp_path），二者必须满足：
- 同属一个文件系统（否则
rename()失败，导致ERR_CONTENT_LENGTH_MISMATCH） - Nginx 工作用户（如
www-data或nginx）对两个目录有 rwx 权限，且父目录具备 x（执行）权限（否则无法进入子目录） - 用
ls -ld /path/to/cache /path/to/temp和ps aux | grep nginx核对属主；修复命令示例：chown -R nginx:nginx /var/cache/nginx /var/lib/nginx/body
第三步：检查缓存键与策略是否匹配业务
缓存键（proxy_cache_key）决定“什么算同一个资源”，策略（proxy_cache_valid）决定“它能活多久”：
- 默认 key 是
$scheme$proxy_host$request_uri，若忽略$cookie_user或$args，会导致登录态混用、参数不同却命中同一缓存 - 确保
proxy_cache_valid覆盖后端实际返回的状态码；例如后端返回200，但配置只写了proxy_cache_valid 404 1m，则该响应永不缓存 - 添加
add_header X-Cache-Status $upstream_cache_status;到 location 中，用curl -I查看响应头；若始终无此头，或值恒为MIS/BYPASS，说明缓存未触发
第四步：排除响应头与绕过逻辑干扰
上游响应头或本地绕过规则可能静默跳过缓存：
- 后端返回
Cache-Control: no-cache、private或no-store，Nginx 默认不缓存；需加proxy_ignore_headers Cache-Control才强制缓存 -
proxy_no_cache和proxy_cache_bypass必须与proxy_cache同在location块内，且不能写在if块中（if内设变量后直接引用会失效）；推荐改用map在http块预定义变量 - 检查 access_log 中
$upstream_cache_status字段：若大量请求为MISS且无HIT，不是流量低，很可能是 key 不稳定或缓存路径未就位
