fastcgi_cache_bypass 用于决定是否跳过缓存：任一变量非空且不为"0"时跳过缓存、直连上游；全为空或"0"才检查缓存有效性；常与 fastcgi_no_cache 配合，前者控读缓存，后者控写缓存。

fastcgi_cache_bypass 的作用不是“匹配缓存”，而是决定“是否跳过缓存”，即：满足条件时，不读缓存、直接转发请求给上游 FastCGI（如 PHP-FPM）；不满足时，才走缓存流程。

它如何工作？

该指令接收一个或多个变量（或字符串），Nginx 会依次求值这些变量：

• 只要任意一个变量的值非空且不为“0”（字符串 "0" 会被视为 false），就触发 bypass —— 即跳过缓存，强制回源；
• 所有变量都为空或等于 "0"，才继续检查 fastcgi_cache_valid 等规则，尝试命中缓存。

注意：它和 fastcgi_no_cache 常配合使用，但语义不同 —— bypass 控制「是否读缓存」，no_cache 控制「是否写缓存」。

Nginx Config Linter

对 Nginx 配置文件进行语法检查、验证和安全、性能审计。

下载

典型用法示例

常见组合是根据 Cookie、参数或请求头绕过缓存：

• fastcgi_cache_bypass $cookie_nocache $arg_nocache $http_pragma $http_authorization;
• 当用户携带 Cookie: nocache=1，或请求带 ?nocache=1，或有 Authorization 头（如登录态），就跳过缓存；
• 这样可让管理员、登录用户或调试请求始终走后端，而普通访客享受缓存加速。

关键细节提醒

变量值判断很严格，容易踩坑：

• $arg_debug 在 URL 中是 ?debug（无值）时，其值为空字符串 → 不触发 bypass；
• 但 ?debug=1 或 ?debug=0，值分别是 "1" 和 "0" → "1" 触发 bypass，"0" 不触发（因 "0" 被视为 false）；
• 若想让 ?debug（有参无值）也 bypass，可用 map 预处理：
  map $arg_debug $bypass_debug { "" ""; default "1"; }，再在 fastcgi_cache_bypass 中引用 $bypass_debug。

调试技巧

确认是否生效，可结合日志与响应头：

• 开启 log_format 记录 $upstream_cache_status，命中缓存显示 HIT，bypass 显示 BYPASS；
• 响应头中查看 X-Cache-Status（需自定义添加）或直接观察 Nginx 日志；
• 临时加 add_header X-Cache-Bypass "$cookie_nocache $arg_nocache"; 辅助验证变量取值。