Nginx通过独立upstream+前缀location+proxy_pass末尾斜杠实现API版本路由：/api/v1/→api_v1、/api/v2/→api_v2，无版本请求兜底v1；自动剥离路径前缀，透传参数与Header；支持健康检查、灰度发布与秒级回切。
要在 Nginx 中为 API 接口配置版本号前缀（如 /api/v1/、/api/v2/）并实现平滑重写与转发，关键不是简单去掉前缀，而是让新旧版本共存、路径语义清晰、后端无感知升级。核心在于：用独立 upstream 隔离版本生命周期，靠 location 前缀匹配精准分流，再通过 proxy_pass 末尾斜杠自动剥离路径，避免硬编码 rewrite。
按版本前缀定义 location 并关联独立 upstream
每个版本对应一个独立 upstream，便于单独做健康检查、权重调整或临时摘除，不干扰其他版本：
- 在
http块中定义：
server 10.0.1.10:8080 max_fails=2 fail_timeout=10s;
}
upstream api_v2 {
server 10.0.1.20:8081 max_fails=2 fail_timeout=10s;
server 10.0.1.21:8081 max_fails=2 fail_timeout=10s;
}
- 在
server块中分别匹配路径前缀：
proxy_pass http://api_v1/;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
location ^~ /api/v2/ {
proxy_pass http://api_v2/;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
注意：^~ 表示前缀匹配优先级最高，不参与后续正则匹配；proxy_pass 末尾的 / 是关键——它会让 /api/v1/users 自动转为 /users 发往后端，无需额外 rewrite。
兼容旧客户端的默认版本兜底
当客户端仍调用 /api/users（无版本号）时，可将其默认路由到 v1，同时保留升级入口：
- 添加 fallback location，放在 v1/v2 规则之后（因匹配顺序从上到下）：
# 若未匹配 v1/v2，则走默认版本
proxy_pass http://api_v1/;
proxy_set_header Host $host;
}
这样既支持显式版本路径，也兼容无版本的老请求，平滑过渡期无需强制客户端改地址。
确保路径剥离与参数完整传递
常见错误是 proxy_pass 不加斜杠，导致路径重复（如 /api/v1/users 被发成 /api/v1/users 到后端）。正确做法依赖两点：
-
location的匹配前缀必须与proxy_pass后的 URL 结构对齐； - 所有版本 location 的
proxy_pass都以/结尾； - 查询参数、请求体、Header 全部原样透传，Nginx 默认不做删减。
例如：GET /api/v2/orders?status=pending&limit=20 → 后端收到 GET /orders?status=pending&limit=20，路径和参数都干净准确。
配合灰度与下线机制提升可靠性
仅靠路径转发还不够，要真正实现“平滑”，需叠加运行时控制能力：
- 新版本上线前，后端服务启动时先返回 503 或失败健康检查，等初始化完成再恢复；
- 通过动态 upstream 管理（如 Consul + nginx-upstream-dynamic 模块）或脚本临时注释掉 v2 的 server 行，实现秒级回切；
- 在 v2 location 中加条件判断，例如只放行指定 Header 或 IP 段的请求，做小流量灰度；
- Nginx 开启内置健康检查（
health_check指令），自动剔除异常节点，避免把请求打到半死服务上。
