proxy_cache_bypass指令可让Nginx跳过缓存直接回源，其值为变量表达式，任一变量非空且不为0即触发绕过，支持自定义Header、参数、Cookie等条件控制，并可通过log和响应头验证生效。
要实现特定请求绕过 Nginx 缓存（即缓存穿透），关键不是“穿透”缓存本身，而是让 Nginx 主动不查缓存、直接回源——proxy_cache_bypass 正是为此设计的指令。它配合请求头（如自定义 Header 或标准 Header）可精准控制哪些请求跳过缓存，常用于调试、灰度、登录态请求或带参动态接口的灵活缓存策略。
理解 proxy_cache_bypass 的触发逻辑
proxy_cache_bypass 的值是一组变量表达式，**只要其中任意一个变量值为非空字符串且不等于 0，Nginx 就跳过缓存，直接转发请求到后端**。它不关心变量内容是什么，只判断“是否有效值”。
- 常见写法：
proxy_cache_bypass $http_x_bypass_cache $arg_nocache; - 当请求携带
X-Bypass-Cache: 1或 URL 中含?nocache=1，该请求就不会读缓存 - 注意：它只影响“是否查找缓存”，不影响
proxy_cache是否启用，也不影响缓存存储行为
通过自定义 Header 实现可控绕过
推荐使用 X- 开头的自定义请求头（如 X-Bypass-Cache），避免与业务或中间件冲突，也便于前端/测试工具显式控制。
- 在 Nginx 配置中添加：
proxy_cache_bypass $http_x_bypass_cache; - 发起请求时带上该 Header：
curl -H "X-Bypass-Cache: true" https://example.com/api/data - 若需更严格（比如只认特定值），可用 map 做映射：
map $http_x_bypass_cache $bypass_flag {<br> "true" 1;<br> "debug" 1;<br> default 0;<br>}
再设proxy_cache_bypass $bypass_flag;
结合 Cookie 或用户状态做条件绕过
对登录用户或特定角色（如管理员）跳过缓存，可基于 $cookie_ 或 $http_authorization 判断：
- 示例：跳过已登录用户的缓存（假设登录态存在 cookie
session_id）：proxy_cache_bypass $cookie_session_id; - 更安全的做法是配合白名单：
map $cookie_role $skip_cache {<br> "admin" 1;<br> default 0;<br>}
然后proxy_cache_bypass $skip_cache; - 注意：
$cookie_*变量自动小写（Cookie: Role=admin→$cookie_role可取到）
调试与验证技巧
绕过是否生效，不能只看响应内容，要确认 Nginx 确实没查缓存：
- 开启缓存日志：
log_format cache '$remote_addr - $request "$upstream_cache_status"';，查看日志中是否出现BYPASS（而非HIT/MIS） - 响应头中检查
X-Cache-Status（需手动添加）：add_header X-Cache-Status $upstream_cache_status; - 临时禁用缓存验证逻辑：把
proxy_cache off;放在 location 内，确认后端能正常响应，再恢复并加 bypass 规则
