map指令通过动态计算布尔值控制proxy_no_cache和proxy_cache_bypass，实现按参数、路径、角色、Cookie等条件实时旁路缓存；需在http块定义map，配合两者同时设置并设default值确保生效。
直接用 map 指令控制 proxy_no_cache，本质是把“要不要跳过缓存”变成一个可计算的布尔值，再让 Nginx 根据这个值决定是否绕过缓存存储和使用。它不靠硬写多个 location 分离逻辑，而是按真实请求特征实时判断，适合混合业务场景。
按请求参数动态旁路缓存
调试或灰度场景常通过 URL 参数触发实时回源，比如 ?debug=1 或带版本号的 ?v=2.3：
- 在
http块中定义映射：
map $args $no_cache_by_arg {<br> ~debug=1 1;<br> ~v=[^&]+ 1;<br> default 0;<br>}
-
$args是完整查询字符串，正则可跨参数匹配；~debug=1能命中a=1&debug=1&b=2这类任意位置的参数；~v=[^&]+匹配v=后非&的内容，覆盖v=beta、v=1.2.0等形式 - 在对应
location中启用：
proxy_no_cache $no_cache_by_arg;<br>proxy_cache_bypass $no_cache_by_arg;
两者必须同时设置：前者禁止存入缓存，后者跳过读取缓存，缺一不可。
按请求路径或角色身份旁路缓存
管理后台、API 调试接口、高权限用户请求通常不应缓存：
- 分别定义路径与角色映射：
map $request_uri $skip_cache_by_path {<br> ~*^/admin/ 1;<br> ~*^/api/v[12]/debug 1;<br> default 0;<br>}<br><br>map $http_x_user_role $skip_cache_by_role {<br> "admin" 1;<br> "dev" 1;<br> default 0;<br>}
FastAPI Flask Proxy
下载
FastAPI + Flask 混合部署最佳实践，解决路由定义、API 代理等常见问题，适用于同时运行 FastAPI API 与 Flask 前端的场景。
- 支持多条件组合，
proxy_cache_bypass和proxy_no_cache都接受多个变量，按“任一为真即生效”处理：
proxy_cache_bypass $skip_cache_by_path $skip_cache_by_role;<br>proxy_no_cache $skip_cache_by_path $skip_cache_by_role;
这样，访问 /admin/dashboard 或携带 X-User-Role: dev 头的请求都会被彻底隔离出缓存链路。
按 Cookie 或认证状态区分游客与登录用户
未登录用户可缓存，登录用户需实时响应：
- 利用 Cookie 判断登录态：
map $cookie_user_id $cache_disabled {<br> "" 0; # 空值 → 允许缓存<br> default 1; # 有值 → 禁用缓存<br>}
- 注意匹配顺序：
default必须放在最后；空字符串""要显式写出，不能省略引号 - 配合使用确保效果完整：
proxy_cache_bypass $cache_disabled;<br>proxy_no_cache $cache_disabled;
当用户携带 User-ID=abc123 Cookie 时，两个指令都收到 1，Nginx 既不查本地缓存，也不存新响应，完全透传到上游。
验证与关键细节提醒
- 所有
map块必须写在http块内，不能放在server或location中 - 正则匹配默认忽略大小写（
~*），但需注意特殊字符转义，例如匹配/api/v1/应写为~*^/api/v1/，避免误中/api/v11/ - 变量未匹配时若无
default，值为空字符串，可能导致指令行为异常，务必设default - 可通过
add_header X-Cache-Status "$upstream_cache_status|$cache_disabled";输出调试头，确认策略是否命中
不复杂但容易忽略。
