return 301 是最简洁高效的重定向方式，适用于废弃路径整体迁移；需用 location = 精确匹配旧路径，配合 $request_uri 完整保留参数，如 location = /api/v1/users { return 301 https://gateway.new.com/v2/users$request_uri; }。
用 return 301 直接跳转是最简洁、高效的做法，尤其适合废弃路径整体迁移到新网关地址的场景。关键不是写得多，而是匹配准、跳得稳、不丢参数。
单路径精确重定向
当旧 API 路径固定且一一对应新网关路径时，直接在 location 块中用 return：
- 把旧路径（如
/api/v1/users）写进location，确保完全匹配 - 用
return 301拼出新网关地址，保留原始查询参数 - 推荐使用
$request_uri，它包含路径 + 查询字符串，比$uri更完整
示例配置：
server {
listen 80;
server_name api.old.com;
location = /api/v1/users {
return 301 https://gateway.new.com/v2/users$request_uri;
}
}
多路径批量迁移（带路径映射）
如果多个旧路径需映射到不同新路径（如 /old/login → /auth/signin），return 不够灵活，改用 rewrite：
- 用正则捕获关键部分（如版本号、资源名），再重构成新路径
-
permanent表示 301，会自动添加Location响应头 - 注意末尾斜杠：proxy_pass 或 rewrite 目标末尾有无
/，决定路径是否被剥离
示例：
location ~ ^/api/v1/(users|posts|orders)/(.*)$ {
rewrite ^/api/v1/(.*)$ https://gateway.new.com/v3/$1/$2 permanent;
}
跨域名 + 协议强制统一
旧 API 在 HTTP，新网关只支持 HTTPS，就不能依赖 $scheme：
- 显式写
https://，避免跳转到不可用的 HTTP 地址 - 若旧域名同时监听 80 和 443，两个
server块都要配，或统一收口到 80 后跳转 - 新网关域名需提前配置好 SSL 证书，否则浏览器会报错
验证与上线要点
配置不是保存就完事，必须验证才敢切流量：
- 运行
nginx -t检查语法，再nginx -s reload生效 - 用
curl -I http://api.old.com/api/v1/users?id=123查看响应头：状态码必须是301 Moved Permanently，Location值要正确且含完整参数 - 测试阶段可临时改
302避免缓存干扰，确认无误后再切回301 - 提醒客户端团队同步更新 SDK 或文档，301 不代表服务器能永远代劳
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
