要让Nginx对特定请求跳过缓存,关键是用proxy_cache_bypass实现不查缓存、直接回源,但必须与proxy_cache同location启用,变量名须为$http_x_refresh_cache(小写、短横变下划线),值非空且不等于"0"或"off",并搭配proxy_no_cache防污染,实测响应头应为X-Cache-Status: BYP。

要让 Nginx 对特定请求跳过缓存,关键不是“删缓存”,而是让这次请求不查本地缓存、直接回源——proxy_cache_bypass 就是干这个的。但它不会自动生效,必须满足几个硬性条件,配置错一点就完全没反应。
必须同 location 启用 proxy_cache
只写 proxy_cache_bypass $http_x_refresh 没用。Nginx 会直接忽略它,除非同一 location 块里明确写了:
-
proxy_cache my_cache;(名称需与proxy_cache_path中定义的keys_zone一致) - 不能只在
http或server块里配 bypass,必须落到具体转发的location
Header 要转成正确的变量名
客户端发 X-Refresh-Cache: 1,Nginx 内部对应的变量是 $http_x_refresh_cache:
- 全部小写
- 短横(-)换成下划线(_)
- 不能写成
$http_X_Refresh_Cache或$http_xrefreshcache
值只要非空、且不等于 "0" 或 "off"(不区分大小写),就触发绕过。例如这些都有效:X-Refresh-Cache: true、X-Refresh-Cache: T、X-Refresh-Cache: force。
建议搭配 proxy_no_cache 防污染
proxy_cache_bypass 只控制“不读缓存”,默认仍会把响应写进缓存(只要状态码匹配 proxy_cache_valid)。如果管理员带 Token 请求用户数据,响应被缓存,后续无权限用户可能命中并拿到敏感内容。
所以生产环境推荐这样配:
proxy_cache_bypass $http_x_refresh_cache;proxy_no_cache $http_x_refresh_cache;
两个指令变量一致,确保既不读旧缓存,也不存新响应。
验证是否真生效
别只看配置,要实测:
- 发起带头请求:
curl -H "X-Refresh-Cache: 1" https://yoursite.com/api/data - 响应头中不应出现
X-Cache: HIT;理想是X-Cache-Status: BYP或无此头 - 日志中
$upstream_cache_status字段应显示BYP,不是HIT


















