最稳妥方式是直接用 return 301 指令，不走正则、不触发 location 匹配、性能高且行为确定；旧接口重定向需精准匹配路径或域名、保留参数、避免循环和开放重定向。
直接用 return 301 指令最稳妥，不走正则、不触发 location 匹配、性能高且行为确定。旧版接口重定向本质是路径或域名变更后的永久跳转，关键在精准匹配、保留参数、避免循环和开放重定向。
明确区分旧接口路径与新接口地址
旧接口通常表现为特定前缀（如 /api/v1/）、子域名（如 old-api.example.com）或完整旧域名（如 v1.example.com）。重定向必须严格对应其入口点，不能笼统写在根 location 下。
用独立 server 块处理旧域名或旧子域名
适用于整个旧域名或子域名整体迁移。例如旧 API 域名 api-v1.example.com 全量迁移到 api.example.com：
- 新建一个仅监听 80（或 443）端口的 server 块
-
server_name明确设为旧域名（如api-v1.example.com） -
return 301 https://api.example.com$request_uri; - 协议写死
https://更安全（避免$scheme在 HTTP 请求下跳转到不安全链接）
按路径前缀重定向旧版 API 接口
如果只是路径升级（如 /api/v1/xxx → /api/v2/xxx），在主站 server 块中用 location 精确匹配：
-
location ^~ /api/v1/ { -
return 301 https://$host/api/v2/$request_uri; - 注意
^~表示前缀匹配且优先于正则，避免被其他 location 覆盖 -
$request_uri自动携带原始查询参数（如?page=1&sort=id），无需额外拼接
避免常见陷阱
- 不要用
rewrite+permanent替代return：rewrite 会触发正则解析和 location 重匹配，容易引发循环或规则冲突 - 别依赖
$host构造跳转地址：若请求 Host 头异常（如 IP 直连、恶意头），$host可能为空，导致跳转 URL 错误（如https:///path） - 所有
return行末尾必须加分号，否则 Nginx 启动失败 - 测试阶段可临时改用
return 302，防止浏览器缓存干扰验证
验证是否生效
-
nginx -t检查语法，再nginx -s reload生效 -
curl -I http://old-api.example.com/api/v1/users查看响应头是否有HTTP/1.1 301 Moved Permanently和正确的Location - 确保新接口地址可访问，且
Location中的路径与$request_uri完全一致（包括斜杠位置和参数）
