使用 proxy_cache_bypass 配合 URL 参数（如 ?_dbg=1）是最轻量安全的线上调试方式，它仅使带参请求绕过缓存并禁止缓存响应，不影响其他用户，且需配合 proxy_cache、合理 cache_key 及 nginx -s reload 生效。
直接用 proxy_cache_bypass 配合 URL 参数（如 ?debug=1 或 ?nocache）是最轻量、最安全的线上调试方式——它不清理旧缓存，也不影响其他用户，只让带参数的请求实时回源，同时还能控制响应是否写入缓存。
配置核心：触发绕过 + 禁止缓存响应
在目标 location 块中加入以下三行：
-
proxy_cache_bypass $arg_debug $arg_nocache;—— 当 URL 中出现?debug=1或?nocache（值非空且不为"0"）时，本次请求跳过缓存，直连后端 -
proxy_no_cache $arg_debug $arg_nocache;—— 同样条件下，禁止将本次响应存入缓存（即使后端返回了Cache-Control: public, max-age=3600也无效） -
add_header X-Cache-Status "$upstream_cache_status" always;—— 在响应头中暴露缓存状态，方便前端或 curl 快速验证（BYP表示已绕过）
推荐的 URL 调试参数组合
线上环境建议固定使用语义清晰、不易误触的参数，避免和业务逻辑冲突：
aperture: the L402 aware reverse proxy
下载
安装并运行 Aperture（Lightning Labs 的 L402 闪电反向代理），用于创建 L402 付费墙、配置付费 API 端点、为其他代理托管付费内容或测试 L402 认证流程。
-
?_dbg=1：下划线前缀降低与正常接口参数冲突概率 -
?v=refresh：用版本标识符形式，便于灰度或临时生效 -
?x-cache=skip：模仿标准 HTTP 头风格，团队协作更易理解
对应配置可写为：proxy_cache_bypass $arg__dbg $arg_v $arg_x_cache;，Nginx 会自动识别变量名中的下划线和短横线。
确保缓存区已启用且键合理
proxy_cache_bypass 必须和 proxy_cache 成对出现才生效。检查 location 中是否已配置：
-
proxy_cache my_cache;（必须指向已在http块中定义的keys_zone） -
proxy_cache_key "$scheme$request_method$host$request_uri";—— 若需支持参数调试，建议保留$args（即完整查询串），否则?_dbg=1和?_dbg=2可能命中同一缓存项 -
proxy_cache_valid 200 302 10m;—— 明确设置有效时间，避免依赖后端Cache-Control导致行为不可控
调试验证方法
无需重启 Nginx，改完配置 nginx -t && nginx -s reload 即可生效。验证步骤：
- 普通请求：
curl -I https://api.example.com/data→ 响应头含X-Cache-Status: HIT或MISS - 调试请求：
curl -I "https://api.example.com/data?_dbg=1"→ 响应头应为X-Cache-Status: BYP，且Age为 0 或缺失 - 检查日志：
$upstream_cache_status在 access log 中会显示BYP，确认已触发绕过逻辑
