Nginx rewrite实现API平滑兼容的核心是网关层收敛版本逻辑：路径前缀重写用break防重复匹配；map指令支持按请求头/参数动态路由，便于灰度；复杂路径重构需正则提取+last重匹配，并清空query string；须配合日志调试与语法校验。
在 Nginx 中用 rewrite 实现旧版 API 的平滑兼容过渡，核心是不改客户端调用、不中断流量、不暴露后端变更——所有版本逻辑由网关层收敛处理。
按路径前缀做内部重写（最常用）
适用于客户端仍调用 /api/v1/users，但后端已统一部署在 /api/ 根路径的场景：
- 在
location /api/v1/块中配置：rewrite ^/api/v1/(.*)$ /api/$1 break; -
必须用
break：防止新 URI 再次进入 location 匹配，避免重复处理或 404 - 若后端服务本身支持多版本共存（如 Spring Boot 的
@RequestMapping("/api")），该方式可零代码适配
用 map 预定义版本路由规则（更灵活可控）
适合需根据请求头、参数或路径动态决定目标版本，且规则较多、需集中维护的场景：
- 在
http块中定义映射：map $http_x_api_version $version_route {<br> default "v1";<br> "2" "v2";<br> "canary" "v2";<br>} - 在
location /api/中结合proxy_pass使用：proxy_pass http://backend_$version_route$request_uri; - 优势：规则清晰、热加载生效、便于灰度（如把特定 Header 或 Cookie 映射到 v2）
旧路径到新版结构的精准映射（重构必备）
当新旧 API 路径结构差异大（如 /user/get?id=1 → /users/1），需正则提取+重组：
- 示例：将
/old/user?id=123改写为/users/123rewrite ^/old/user\?id=(\d+)$ /users/$1? last; - 注意结尾的
?：清空原始 query string，避免拼出/users/123?id=123 - 用
last触发重新匹配 location，确保新路径能被正确 proxy_pass 或 serve
兜底与安全防护建议
rewrite 是主动映射，但不能替代容错机制：
- 加
if (!-f $request_filename) { rewrite ... last; }可配合静态资源判断，但 API 场景更推荐用map + proxy_next_upstream做失败回退 - 所有 rewrite 规则前建议加日志调试：
log_format rewrite_log "... $request_uri → $uri";<br>access_log /var/log/nginx/rewrite.log rewrite_log;
- 上线前务必执行
nginx -t检查语法，并用curl -v验证重写结果是否符合预期
