Nginx通过rewrite实现API版本优雅升级：前缀匹配重写（如^~ /api/v1/）可静默映射至/api/或/api/v2/，配合last/break控制流程；结合map指令支持按请求头或参数动态路由；务必用$request_uri或正则捕获保留查询参数，并添加兜底健康检查保护。
用 rewrite 实现 API 接口版本号的优雅升级，核心是把带版本号的请求路径（比如 /api/v1/users）在 Nginx 层内部重写为后端实际能处理的新路径（如 /api/v2/users 或 /api/users），客户端无感知、不跳转、不改代码。
按路径前缀重写（最常用、最直观）
适合 URL 已统一规划、旧客户端大量存在、需长期兼容的场景。例如所有 v1 请求走 /api/v1/xxx，但后端新服务只监听 /api/xxx 或 /api/v2/xxx。
- 将
/api/v1/全部映射到新服务根路径：location ^~ /api/v1/ {<br> rewrite ^/api/v1/(.*)$ /api/$1 break;<br>} - 若新服务部署在
/api/v2/，想静默升级旧调用：location ^~ /api/v1/ {<br> rewrite ^/api/v1/(.*)$ /api/v2/$1 last;<br>}
注意：用last会重新匹配 location，适合需要进入新 location 块做 proxy_pass 的情况；break则终止重写，在当前 location 内继续处理。 - 避免正则误伤：用
^~ /api/v1/而非~ /api/v1/，确保前缀匹配优先级高，不被其他正则规则干扰。
用 map + rewrite 实现动态路由（支持灰度与多版本共存）
当需要按请求头、参数或业务标识分流（比如部门 ID=101 走 v2，其余走 v1），仅靠 rewrite 不够，必须结合 map 指令预定义变量。
linux-sysadmin
下载
Linux系统管理专家，覆盖12大模块：用户权限、SSH、存储、网络、systemd、防火墙、日志监控、备份恢复、TLS证书、Ansible、容器、IaC。提供配置、验证、加固、监控、备份、自动化、故障排查、回滚闭环。关键词：useradd、sudo、sshd_config、chmod、SEL...
- 在
http块中定义版本映射：map $http_x_api_version $backend_path {<br> default "/v1";<br> "2" "/v2";<br> "canary" "/v2";<br>} - 在 location 中使用：
location /api/ {<br> proxy_pass http://backend$backend_path$request_uri;<br>}
这样X-API-Version: 2的请求自动转发到http://backend/v2/...，URL 干净，也便于 AB 测试。 - 也可结合查询参数：
map $arg_version $backend_path {<br> default "/v1";<br> "2" "/v2";<br>}
让?version=2触发切换，开发调试友好。
重写时保留原始参数与请求头
rewrite 只改 URI 路径，不会自动携带原查询参数。若目标路径需透传参数，要用 $request_uri 或显式拼接。
- 错误写法（丢参数）：
rewrite ^/api/v1/users$ /api/v2/users;
→/api/v1/users?id=123变成/api/v2/users，参数丢失。 - 正确写法（保留全部）：
rewrite ^/api/v1/users(.*)$ /api/v2/users$1 break;
或更稳妥：rewrite ^/api/v1/(.*)$ /api/v2/$1 break;
再配合proxy_pass使用$request_uri，确保完整转发。 - 如需注入新请求头（如标记版本来源）：
proxy_set_header X-Api-From "v1-rewrite";
上线前必做的三件事
rewrite 规则一旦出错容易导致 404、循环重定向或覆盖健康检查路径，必须验证到位。
- 语法校验：
nginx -t确保配置无误； - 作用域测试：用
curl -v http://host/api/v1/users看响应头Location是否出现（不该有）、后端日志是否收到预期路径； - 兜底保护：用
location ^~ /health或/metrics单独配置，防止 rewrite 规则误匹配运维接口。
