缓存绕过条件不生效，主因是变量未被识别、作用域错误、值不满足非空非0/off规则，或被proxy_no_cache等指令干扰；需确保proxy_cache_bypass在location块内与proxy_pass同级，变量合法且已初始化，日志验证值有效，并排查CDN/WAF透传问题。
缓存绕过条件不生效，通常不是配置写错了，而是变量没被识别、作用域不对、值不符合触发规则，或者被其他指令覆盖。重点不是“有没有配”，而是“有没有被真正执行”。
检查变量是否在正确位置定义且可被读取
proxy_cache_bypass 只在 location 块内有效，server 或 http 块里写的变量完全不会起作用。
- 确认该指令与 proxy_pass、proxy_cache 在同一个 location 中；单独放在 upstream 或 server 块里，Nginx 会静默忽略
- 变量名必须是 Nginx 能解析的合法变量，例如 $http_x_bypass_token、$arg_bypass，不能是自定义未声明的 $bypass_flag
- 若用 map 指令生成变量，需确保 map 块在 http 级别定义，且变量在 location 中被引用时已初始化（比如 map 里用了 $arg_debug，但请求没带 ?debug=1，则变量为空，不触发绕过）
验证变量值是否满足“非空且非 0/off”条件
Nginx 对 proxy_cache_bypass 的触发判断非常严格：变量值只要为空字符串、"0"、"off"、"false" 就视为不绕过。
- 用 curl -v 加上对应参数或 header 测试，例如 curl -H "X-Bypass-Token: abc" https://a.com/api —— 查看响应头 X-Cache-Status 是否为 BYP
- 在 access_log 中加入 $http_x_bypass_token 或 $arg_bypass 字段，确认日志中该字段确实有值，且不是空或 "0"
- 避免前端传 "bypass=0" 这类语义反向的值；建议统一约定非空即绕过，如存在 X-Bypass-Token 头就触发
排查是否被其他缓存相关指令干扰
一个 location 中多个缓存指令可能互相压制，尤其 proxy_no_cache、proxy_ignore_headers 和 proxy_cache_valid 容易掩盖绕过行为。
- proxy_no_cache 和 proxy_cache_bypass 必须配对使用：只设 bypass 不设 no_cache，会导致绕过请求的响应仍被缓存，后续普通请求可能拿到污染内容
- 如果配置了 proxy_ignore_headers Cache-Control，Nginx 就无法从响应头读取 max-age，可能导致 proxy_cache_valid 生效异常，间接影响 bypass 判断逻辑（比如误判为 EXPIRED 而非 BYPASS）
- 检查是否有 rewrite 或 set $args 操作在 proxy_pass 前修改了原始请求，导致 $arg_xxx 类变量丢失或变形
确认绕过是否被更高层级代理提前拦截
如果 Nginx 前面还有 CDN、WAF 或 API 网关，它们可能在到达 Nginx 前就处理了 bypass 参数或 header，并做了自己的路由决策。
- 在 Nginx access_log 中加 $remote_addr 和 $http_x_forwarded_for，对比客户端真实 IP 和经过几层代理后的地址，确认请求是否真抵达了这台 Nginx
- 临时在 location 中加 log_format full '$remote_addr - $http_x_bypass_token - $request';，观察日志里 bypass 相关字段是否为空——若为空，大概率是上层代理未透传
- CDN 厂商常默认过滤掉自定义 header（如 X-Bypass-Token），需在 CDN 控制台显式开启 header 透传白名单
