Nginx 中 proxy?cache?bypass 实现按需缓存配置

proxy_cache_bypass用于条件跳过缓存读取，必须与proxy_no_cache协同使用才能实现“既不读也不写缓存”；其触发逻辑为任一变量非空且非”0″/”off”即生效，常配合map预处理登录态、参数、请求头等信号，并在location中成对启用双指令。

proxy_cache_bypass 是 Nginx 缓存机制中控制“跳过缓存”的关键指令，它不决定是否缓存响应，而是决定请求是否绕过已有的缓存直接回源——常被误认为是“关闭缓存”，实际作用是“按条件跳过缓存读取”。要实现真正按需缓存（比如登录用户不缓存、API 某些参数强制不缓存），必须配合 proxy_cache_bypass 和 proxy_no_cache 协同使用。

理解 proxy_cache_bypass 的触发逻辑

该指令接收一个或多个变量（如 $cookie_user, $arg_nocache），只要其中任意一个变量值为非空且非 0（字符串非空、数值非 0），Nginx 就认为条件满足，**本次请求不读缓存，直接转发给后端**。注意：它不影响缓存的写入——即使 bypass 生效，后端返回的响应仍可能被缓存（除非同时配置 proxy_no_cache）。

• 值为 ""（空字符串）、"0"、"off" 视为 false，不 bypass
• 值为 "1"、"on"、"yes" 或任意非空非零字符串视为 true，触发 bypass
• 支持多变量：proxy_cache_bypass $cookie_sessionid $arg_preview;

常见按需缓存场景与配置示例

典型需求如“带 token 的请求不走缓存”“含 debug 参数的请求直连后端”“POST 请求默认不缓存”，需结合变量判断：

• 跳过已登录用户的缓存：proxy_cache_bypass $cookie_token $arg_auth;
• 忽略调试参数：proxy_cache_bypass $arg_debug $arg_v;（访问 ?debug=1 时直连）
• 区分请求方法：proxy_cache_bypass $http_pragma $http_authorization;（带 Authorization 头即 bypass）
• 避免 POST 被缓存读取：proxy_cache_bypass $request_method;（但需注意 GET/HEAD 才会缓存，POST 默认不缓存，此条主要防误配）

必须搭配 proxy_no_cache 才能真正“不缓存”

仅用 proxy_cache_bypass 只影响“读缓存”，后端返回的响应仍会被存入缓存区。若希望某些请求**既不读缓存也不写缓存**，必须同步设置 proxy_no_cache：

• 两者变量一致即可：proxy_no_cache $cookie_token $arg_nocache;
• 也可用不同条件：proxy_no_cache $http_x_no_cache;（识别自定义请求头）
• 注意：proxy_no_cache 为 true 时，响应头自动添加 X-Cache: BYPASS（需开启 add_header X-Cache $upstream_cache_status; 查看）

验证与调试技巧

配置生效后，通过响应头 X-Cache 判断是否命中或跳过：

• HIT：读缓存成功
• MISS：缓存未命中，回源并写入缓存
• BYPASS：因 proxy_cache_bypass 或 proxy_no_cache 触发，不读也不写缓存
• 用 curl 测试：curl -I "https://example.com/?debug=1" 查看 X-Cache 值
• 检查 error_log 中 cache 相关日志（需设置 error_log /path/log warn;）