proxy_cache_bypass 用于定义哪些请求不走缓存、直接回源，其值为真时绕过缓存，所有参数均为假时才进入缓存流程，需配合 proxy_cache_key 实现精准缓存隔离。

在 Nginx 中，proxy_cache_bypass 的作用不是“建立清单”，而是定义哪些请求**不走缓存、直接回源**——它是一个布尔条件列表，每项求值为非零（true）时，就跳过缓存，强制代理到后端。

理解 proxy_cache_bypass 的匹配逻辑

该指令接收一组变量或字符串，Nginx 会依次检查每个参数：

• 只要其中任意一个参数的值为非空字符串、非零数字或“1”、“on”、“true”等真值，整个请求就被视为需绕过缓存；
• 所有参数均为假（空字符串、0、“off”、“false”等）时，才进入缓存流程；
• 它不依赖“白名单”或“黑名单”式配置，而是靠运行时变量动态判断，比如检查 Cookie、Header 或自定义变量。

常用动态跳过场景与写法

典型需求是：登录用户、带调试参数、特定设备或未认证请求不缓存。示例如下：

FastAPI Flask Proxy

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

下载

• 跳过含特定 Cookie 的请求：proxy_cache_bypass $cookie_user_id $cookie_session; —— 只要任一 Cookie 存在且非空，就绕过缓存；
• 跳过带 debug 参数的请求：proxy_cache_bypass $arg_debug; —— URL 中含 ?debug=1 或 ?debug=any 即生效；
• 跳过非 GET/HEAD 请求：proxy_cache_bypass $request_method; —— 因 POST/PUT 等方法默认值为自身字符串（非空），自然绕过；
• 组合多个条件（推荐）：proxy_cache_bypass $cookie_auth $arg_nocache $http_pragma; —— 满足任一即跳过。

配合 proxy_cache_key 实现精准控制

仅靠 proxy_cache_bypass 不足以保证缓存隔离，还需确保缓存键能区分不同用户状态：

• 若用 $cookie_user_id 控制是否缓存，那么 proxy_cache_key 也应包含该变量，避免未登录用户命中已登录用户的缓存；
• 例如：proxy_cache_key "$scheme$request_method$host$request_uri$cookie_user_id";
• 否则即使 proxy_cache_bypass 正确跳过，缓存内容仍可能被错误复用。

调试与验证技巧

实际部署前建议验证行为是否符合预期：

• 在响应头中添加标识：add_header X-Cache-Status "$upstream_cache_status";，观察返回 MISS（未命中）、HIT（命中）或 BYPASS（被 bypass）；
• 用 curl 模拟不同请求：curl -H "Cookie: user_id=abc" http://example.com/api，对比有无 Cookie 时的 X-Cache-Status；
• 注意变量大小写：HTTP 头转为变量时，Cache-Control → $http_cache_control，全小写加下划线。