缓存绕过异常若由代理头丢失引发，核心表现是请求直连后端时因Cookie、Authorization等关键header未透传，导致后端无法识别用户身份，误判为普通缓存请求；需通过日志比对、curl验证及逐层检查header透传链路确认并修复。
缓存绕过异常若由代理头丢失引发，核心表现是：请求本应绕过缓存直连后端，却因关键 header（如 Cookie、Authorization、X-Forwarded-For）未透传，导致后端无法识别用户身份或上下文，误判为普通缓存请求——结果看似“绕过失败”，实则是后端收不到判断依据。
确认是否真因 header 丢失触发绕过逻辑失效
proxy_cache_bypass 和 proxy_no_cache 的触发依赖变量值，而这些变量往往来自请求头。如果 header 在抵达 Nginx 前就被过滤，或在 Nginx 内部未被正确提取，变量就为空，绕过规则自然不生效。
- 检查日志中绕过变量实际值：在 location 中加 log_format，例如 log_format bypass_debug '$remote_addr - $request - $http_cookie - $http_authorization - $arg_nocache';，观察 access_log 里对应字段是否为空
- 用 curl 模拟带 header 的请求：curl -H "Cookie: session=abc" -H "Authorization: Bearer xyz" "https://domain.com/api?nocache=1" -I，再对比不带 header 的响应头中 X-Cache-Status 是否均为 HIT/MISS/BYPASS
- 特别注意：若后端依赖 X-User-ID 或 X-App-Version 等自定义头做灰度路由，而 Nginx 未显式透传，$http_x_user_id 就永远为空，proxy_cache_bypass $http_x_user_id 永远不触发
排查 header 丢失的常见链路断点
header 不是凭空消失，而是卡在某一层转发环节。需逐层验证：
- 客户端到 Nginx 之间：检查是否有 CDN、WAF 或浏览器插件主动剥离敏感头（如某些安全策略默认过滤 Authorization）；用 curl 直连 Nginx IP（绕过 CDN），看 header 是否还在
- Nginx 自身过滤机制：默认会丢弃含下划线的 header（如 api_key → 变量名应为 $http_api_key，但需先开启 underscores_in_headers on;）；同时确认未设置 ignore_invalid_headers on;（它会静默丢弃非常规头）
- Nginx 到后端之间：即使 header 进来了，若没在 proxy_pass 块中用 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; 显式传递，后端就收不到；Authorization、Cookie 等同样需手动透传，不能只靠 proxy_pass_request_headers on;（它只传标准头）
验证与修复关键 header 的透传链路
不要假设“写了 proxy_set_header 就一定生效”。必须端到端验证每个头是否从客户端完整抵达后端。
- 在后端入口打日志，输出所有收到的 header 名称和值（例如 Java 中 request.getHeaderNames()，Node.js 中 Object.keys(req.headers)）
- 在 Nginx access_log 中记录原始头：log_format full_req '$http_cookie $http_authorization $http_x_user_id $http_x_app_version';，对比前后端日志是否一致
- 对必须透传的头，统一加显式声明（示例）：
proxy_set_header Cookie $http_cookie;
proxy_set_header Authorization $http_authorization;
proxy_set_header X-User-ID $http_x_user_id;
proxy_set_header X-App-Version $http_x_app_version;
绕过配置本身是否依赖了易丢失的 header
有些绕过规则用的是不稳定或易被清理的头，比如：
- 依赖 Referer：CDN 或浏览器隐私模式可能清空它，$http_referer 为空 → 绕过失效
- 依赖 User-Agent：某些代理会重写 UA，或移动端 UA 过长被截断，导致匹配失败
- 依赖 query string（如 ?debug=1）：比 header 更可靠，建议优先用 $arg_debug 替代 $http_x_debug
更稳妥的做法是组合多个变量：proxy_cache_bypass $arg_nocache $http_x_force_bypass $cookie_dev_mode;，任一有效即绕过。
