Nginx 实现多版本 API 分发需通过独立 upstream 分组、按 Header/路径/参数精准路由、健康检查与灰度发布保障平滑过渡。
要让 Nginx 同时分发多个版本的 API（比如 v1 和 v2），关键不是简单轮询，而是实现**按需路由 + 版本隔离 + 平滑过渡**。核心在于用 upstream 分组管理不同版本服务，并通过请求特征精准分流，避免混用或误切。
定义独立的 upstream 分组
每个 API 版本应有专属 upstream，不共用、不交叉，便于单独扩缩容、健康检查和下线：
- 为 v1 创建
upstream api_v1，指向 v1 实例（如10.0.1.10:8080、10.0.1.11:8080） - 为 v2 创建
upstream api_v2，指向 v2 实例（如10.0.1.20:8081、10.0.1.21:8081） - 可在各 upstream 内设置
weight、max_fails、fail_timeout，控制流量倾向与容错行为
按请求特征选择目标版本
推荐优先使用 HTTP Header 路由，客户端明确声明版本，语义清晰且不侵入路径结构：
-
Header 路由：检查
$http_x_api_version，匹配v2就走api_v2，否则走api_v1 -
路径前缀路由：如
location /v2/→proxy_pass http://api_v2，适合客户端已适配新路径的场景 -
Query 参数路由：如
if ($arg_version = "v2") { proxy_pass http://api_v2; }，适合临时调试，不建议长期用于生产
启用健康检查与可控下线机制
版本切换是否平滑，取决于旧版能否安全退出。Nginx 本身不主动感知服务状态，需配合后端协作：
- 在后端启动时，先返回
503或失败健康检查响应，等初始化完成再开放 - 下线前，后端主动通知 Nginx（如调用 Consul 接口或更新配置），或人工临时注释掉对应
server行并重载 - 可开启
health_check（需编译含 http_upstream_health_check_module），定期探测/health端点自动剔除异常节点
灰度发布与验证流程
上线 v2 不是一次性全量切换，而应分阶段验证稳定性：
- 初期只对内部 IP 或特定 Header（如
X-Env: staging）放行 v2 流量 - 逐步扩大范围，例如按用户 ID 哈希分配 5% → 20% → 全量
- 监控 v2 的错误率、延迟、成功率，确认达标后再关闭 v1 的入口或降权
