要让Nginx反向代理跳过缓存，必须在启用proxy_cache的location块中同时配置proxy_cache_bypass和proxy_no_cache，且共用同一变量（如$http_x_refresh），变量值非0、非off、非空即生效，并需确保keys_zone名称一致及请求头转义正确。

要让 Nginx 在反向代理中对特定请求跳过缓存，核心是用 proxy_cache_bypass 控制“不读缓存”，同时必须搭配 proxy_no_cache 防止响应被误存——二者缺一不可，且必须共用同一套判断变量。

必须和 proxy_cache 成对出现在 location 块中

单独写 proxy_cache_bypass 没有效果。Nginx 只在启用缓存的 location 里才识别它。

• ✅ 正确：location 块内同时存在 proxy_cache mycache 和 proxy_cache_bypass $http_x_refresh
• ❌ 错误：只在 server 或 http 块里配置 bypass，但对应 location 没有 proxy_cache
• ⚠️ 注意：mycache 必须与 proxy_cache_path 中定义的 keys_zone 名称完全一致

请求头要转成正确的内部变量名

客户端发送的 HTTP 头（如 X-Refresh），Nginx 内部对应变量需严格遵循命名规则：

Nginx Config Linter

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

下载

• 全部小写
• 短横线 - 替换为下划线 _
• 统一加前缀 $http_

例如：
X-Refresh → $http_x_refresh
X-Admin-Bypass → $http_x_admin_bypass
X-Gray-Preview → $http_x_gray_preview

值判断逻辑要符合要求

只要变量展开后满足以下任一条件，就会触发绕过：

• 值是非空字符串（如 "1"、"true"、"force"）
• 值不是 "0"（不区分大小写）
• 值不是 "off"（不区分大小写）

有效请求示例：
curl -H "X-Refresh: true" /api/data
curl -H "X-Refresh: T" /api/data
无效请求示例：
curl /api/data（无 Header）
curl -H "X-Refresh: 0" /api/data

务必搭配 proxy_no_cache 防止缓存污染

proxy_cache_bypass 只跳过读缓存，不阻止写缓存。如果带身份信息的响应被缓存，后续普通用户可能命中并拿到敏感数据。

• 推荐统一使用相同变量：
  proxy_cache_bypass $http_x_refresh;
proxy_no_cache $http_x_refresh;
• 更稳妥的做法是用 map 提前定义业务规则，比如按路径、角色、Cookie 或参数生成布尔变量，再在 location 中统一传入两个指令
• 验证是否生效：检查响应头是否缺失 X-Cache: HIT，日志中 $upstream_cache_status 应为 BYPASS 或 MISS