proxy_cache_bypass 是缓存绕过指令，当指定变量非空且不为"0"/"off"时跳过缓存直连后端，需与proxy_cache、proxy_cache_valid同location配置，并配合proxy_no_cache防污染，响应头X-Cache-Status: BYP可验证生效。

proxy_cache_bypass 是 Nginx 缓存机制中用于“绕过缓存”的关键指令，它决定哪些请求不走缓存，而是直接转发给后端服务。它的核心逻辑是：当指定的变量值为非空、非“0”、非“off”时，Nginx 就跳过缓存查找，直接代理请求。

理解 proxy_cache_bypass 的匹配逻辑

该指令接收一个或多个变量（如 $cookie_xxx、$arg_nocache、$http_x_no_cache 等），Nginx 会依次检查这些变量：

• 只要有一个变量的值非空字符串、且不等于 "0"、也不等于 "off"（大小写敏感），就触发 bypass；
• 所有变量都为空、为 "0" 或为 "off" 时，才进入缓存流程；
• 变量本身未定义（即未在请求中出现）等价于空字符串，不会触发 bypass。

常用 bypass 场景与配置示例

实际中常结合业务需求设置 bypass 规则，例如调试、登录态请求、带特定参数的请求等：

FastAPI Flask Proxy

FastAPI + Flask 混合部署最佳实践，解决路由定义、API 代理等常见问题，适用于同时运行 FastAPI API 与 Flask 前端的场景。

下载

• 按请求头绕过：比如客户端发送 X-No-Cache: 1 时跳过缓存：
  proxy_cache_bypass $http_x_no_cache;
• 按查询参数绕过：访问 /api/data?nocache=1 时不走缓存：
  proxy_cache_bypass $arg_nocache;
• 按 Cookie 绕过：对已登录用户（如含 session_id Cookie）不缓存：
  proxy_cache_bypass $cookie_session_id;
• 组合多个条件：满足任一即可 bypass：
  proxy_cache_bypass $http_x_no_cache $arg_nocache $cookie_admin;

注意与 proxy_cache_key 和 proxy_cache_valid 的协同

bypass 只影响“是否查缓存”，不改变缓存键或缓存有效期：

• 即使设置了 bypass，proxy_cache_key 仍会照常计算（只是不使用）；
• proxy_cache_valid 定义的缓存时间，只对未被 bypass 的响应生效；
• 若同时用了 proxy_cache_use_stale，bypass 不影响 stale 判定逻辑。

调试 bypass 是否生效的小技巧

可通过响应头快速验证缓存行为：

• 开启 add_header X-Cache-Status "$upstream_cache_status";；
• 返回 HIT/MISS/BYPASS —— 当看到 BYPASS，说明规则已命中；
• 配合 curl 测试：curl -H "X-No-Cache: 1" http://your-domain/，观察响应头和后端日志。