缓存键配置语法错误不会直接让缓存“完全失效”，但会引发缓存逻辑错乱——比如键生成失败、被降级为默认行为、或始终生成空/非法键，最终导致请求全部回源，表现就是缓存命中率归零、上游压力陡增。
缓存键配置语法错误不会直接让缓存“完全失效”，但会引发缓存逻辑错乱——比如键生成失败、被降级为默认行为、或始终生成空/非法键，最终导致请求全部回源，表现就是缓存命中率归零、上游压力陡增。排查重点不是找“错误提示”，而是验证“键是否按预期生成并复用”。
确认 proxy_cache_key 是否被正确解析
Nginx 不会因 proxy_cache_key 中变量拼写错误（如写成 $http_useragent 而非 $http_user_agent）报错，而是静默替换为空字符串，导致键变成类似 "https://example.com/" 这种固定值，所有请求都挤进同一个缓存槽，造成污染或覆盖。
- 检查配置中所有变量名：对照 Nginx 官方文档的 内置变量列表，确认大小写、下划线、前缀（
$http_、$sent_http_）无误 - 用
curl -I -H "X-Test: abc" http://your.site/path和curl -I -H "X-Test: xyz" http://your.site/path对比响应头中的X-Cache-Key（需在配置中加add_header X-Cache-Key "$scheme://$host$request_uri $http_x_test";） - 若两个请求返回的
X-Cache-Key完全一样，说明$http_x_test没被识别，变量名很可能写错了
警惕变量未定义时的默认行为
Nginx 对未定义变量不报错，而是取空值。例如 proxy_cache_key $scheme$host$request_uri$is_args$args$http_authorization; 中，若请求没带 Authorization 头，$http_authorization 就是空，整个键变成 https://api.example.com/v1/user??（多出一个问号），和带 token 的键不一致，但你根本看不出问题。
- 在测试环境临时启用
log_format cache_debug '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" "$http_authorization" "$upstream_http_x_cache_key"';，配合access_log /var/log/nginx/cache-debug.log cache_debug; - 观察日志里
$http_authorization是否为空、$upstream_http_x_cache_key（需后端透传）是否稳定 - 对必须参与键计算的变量，用
map提供默认值：例如map $http_authorization $auth_for_cache { "" "anon"; default $http_authorization; }，再在proxy_cache_key中用$auth_for_cache
验证缓存键是否实际生效而非被绕过
即使 proxy_cache_key 语法正确，也可能因其他指令干扰而无法进入缓存流程。最常见的是 proxy_no_cache 或 proxy_cache_bypass 配置错误，把本该缓存的请求全放行了。
- 执行
nginx -t后，检查 error.log 是否有类似invalid number of arguments in "proxy_no_cache" directive的警告（这类警告常被忽略，但会导致整条指令失效） - 在 location 块中添加临时调试头：
add_header X-Cache-Bypass "$proxy_cache_bypass"; add_header X-No-Cache "$proxy_no_cache";，用 curl 查看响应头，确认值是0或空（表示不绕过），而不是1或非空字符串 - 特别注意布尔型指令不能混用字符串字面量：错误写法
proxy_no_cache "1"或proxy_cache_bypass $arg_nocache "true"都无效；正确写法只用变量或数字0/1，如proxy_no_cache $arg_nocache;
检查缓存路径与 keys_zone 是否匹配
proxy_cache_path 中定义的 keys_zone=name:size 必须和 proxy_cache name; 中的 name 完全一致，且该 zone 必须在 http 块中声明。名称不匹配不会报错，但缓存不会写入，所有请求都回源。
- 运行
nginx -T 2>/dev/null | grep -A5 "proxy_cache_path\|proxy_cache"，确认 keys_zone 名称拼写、大小写、分号位置完全一致 - 检查
proxy_cache是否写在location块内（合法），而非if块或嵌套错误的位置（Nginx 不允许） - 用
sudo ss -tulnp | grep :80确认 Nginx 已加载新配置；若 reload 后仍无缓存效果，可能是 worker 进程还在用旧配置，尝试sudo nginx -s reload后再sudo kill -USR2 $(cat /var/run/nginx.pid)强制重启 worker
