本质是让Nginx跳过缓存查找、直接回源，不清理旧缓存也不影响其他请求；需在启用proxy_cache的location中配置proxy_cache_bypass与proxy_no_cache，并通过X-Cache-Status或$upstream_cache_status验证BYP状态。
用 proxy_cache_bypass 配合自定义 Header（比如 X-Debug-Bypass-Cache）实现强制回源，本质是让 Nginx 在收到特定请求时跳过缓存查找，直接把请求发给后端。它不清理旧缓存，也不影响其他请求，轻量、实时、无需重启配置。
核心配置写法
在启用缓存的 location 块中添加以下三行（顺序和共存很重要）：
-
启用缓存区：必须有
proxy_cache my_cache;，否则bypass失效 -
触发绕过条件：写
proxy_cache_bypass $http_x_debug_bypass_cache;，Nginx 会自动读取请求头X-Debug-Bypass-Cache的值 -
避免误存响应：加上
proxy_no_cache $http_x_debug_bypass_cache;，确保带该 Header 的响应不会被缓存下来
Header 值怎么才算“有效”
Nginx 判断是否绕过的逻辑很直接：只要变量展开后是非空字符串，且不等于 "0"、"off" 或 ""，就触发 bypass。
-
X-Debug-Bypass-Cache: 1→ 触发 -
X-Debug-Bypass-Cache: true→ 触发 -
X-Debug-Bypass-Cache:（空值）→ 不触发 -
X-Debug-Bypass-Cache: 0→ 不触发
如果需要更严格控制（例如只认 "1"），可写成：proxy_cache_bypass "$http_x_debug_bypass_cache" = "1";
快速验证是否生效
不用等上线，本地就能测：
- 用 curl 发起对比请求：
curl -H "X-Debug-Bypass-Cache: 1" https://example.com/api/datacurl https://example.com/api/data - 检查响应头是否含
X-Cache-Status: BYP（需提前配add_header X-Cache-Status $upstream_cache_status;） - 看 Nginx access 日志里的
$upstream_cache_status字段：从HIT变成BYP或MISS就说明成功了
生产环境要注意的安全细节
线上用这个功能，不能只靠 Header 名字防误触：
- 避免用通用名如
X-No-Cache，浏览器或 CDN 可能识别并透传 - 推荐用语义明确、低冲突的名称，比如
X-Preview或X-Admin-Refresh - 高敏感场景可叠加 IP 限制：
proxy_cache_bypass $http_x_preview $remote_addr ~^(10\.10\.100\.) - 确保后端服务忽略该 Header，不记录、不报错、不改变业务逻辑
