nginx 中用 map 指令配合 upstream 实现基于 header 的后端路由分发最稳定可靠，map 必须置于 http 块顶层，源变量带 $ 前缀，目标变量不可预先定义，下划线 header 需开启 underscores_in_headers on，proxy_pass 引用变量时不可带斜杠，且需搭配语义化 upstream 分组与健康检查。
用 map 指令配合 upstream 实现基于 Header 的后端路由分发，是 Nginx 最稳定、可维护性最强的方式。它不依赖 if 判断，避免路径重写错乱，也支持默认兜底和正则匹配，适合灰度、多版本、多环境等真实场景。
必须把 map 写在 http 块顶层
map 是全局映射指令，只能出现在 http{} 块里，和 upstream、include 同级。写在 server 或 location 中会直接导致 Nginx 启动失败，报错：nginx: [emerg] "map" directive is not allowed here。
- 源变量名要带
$，比如$http_x_env（对应请求头X-Env） - 目标变量不能提前被定义过，例如不能先用
set $backend再 map 赋值 - Header 名自动转为小写+下划线格式：
X-Api-Version→$http_x_api_version
Header 带下划线时要开启支持
默认情况下，Nginx 会丢弃所有含下划线的请求头（如 X_User_Id），因为 RFC 规定 header 名只允许字母、数字和连字符。若客户端确实发送了这类 Header，需显式启用：
Skill Weave Chains — 技能链路由引擎
下载
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。
- 在
http或server块中添加：underscores_in_headers on; - 启用后仍需按规范引用：
X_User_Id对应$http_x_user_id，不是$http_x_user_id - 该设置不影响连字符命名的 Header（如
X-Forwarded-For），仅放开下划线支持
proxy_pass 引用变量有严格规则
用变量控制转发目标时，proxy_pass 的写法直接影响路径透传是否正确：
- ✅ 正确：
proxy_pass http://$backend_upstream;（无斜杠）→ 完整保留原始 URI，如/api/v2/user透传到后端 - ❌ 错误：
proxy_pass http://$backend_upstream/;（带斜杠）→ 强制重写为根路径，/api/v2/user变成/ - 变量值必须是合法 upstream 名或完整 URL（如
http://10.0.1.10:8080），不能含路径段 - 若需改写路径（如去掉前缀
/v2），要用rewrite ... break;单独处理，不能和 proxy_pass 变量混在 if 里
结合 upstream 实现分组与健康检查
每个目标后端应定义独立的 upstream 组，便于隔离管理、设置权重和启用健康探测：
- 为不同版本或环境建语义化组名，例如：
upstream api_v1、upstream cdn_origin - 组内可设
weight控制流量比例，max_fails和fail_timeout控制容错 - 加
backup标记备用节点，或用down临时下线实例而不删配置 - 如需主动健康检查，需确保编译时包含
upstream_health_check_module，再配置check指令探测/health
