nginx rewrite本质是修改客户端url或内部路径，非代理转发；需区分rewrite（改url）与proxy_pass（转发请求）；常见场景包括域名301跳转、路径重写+反向代理、条件化重定向，并注意break/last、proxy_pass末尾斜杠及if使用限制。
Nginx 实现请求重定向（Rewrite）本质是修改客户端看到的 URL 或内部处理路径，不是代理转发。很多人混淆了 rewrite（重写/重定向） 和 proxy_pass（反向代理） 的用途：
-
rewrite是改 URL，让浏览器跳转或内部路径替换； -
proxy_pass是把请求发给后端服务，用户地址栏不变。
如果你真正需要的是“通过 Nginx 改变请求路径后再转发”，那其实是 rewrite + proxy_pass 的组合；如果只是想让用户访问 A 地址自动跳到 B 地址，直接用 rewrite 就够了。
域名级 301 永久跳转
适用于旧域名停用、SEO 权重迁移等场景。
比如把 http://old.com 全量跳到 https://new.com，保留原路径：
server {
listen 80;
server_name old.com www.old.com;
return 301 https://new.com$request_uri;
}
✅ 关键点：
-
return 301比rewrite ... permanent更高效、更安全（避免正则开销和潜在循环）； -
$request_uri包含路径+查询参数，确保/a/b?c=1→/a/b?c=1； - 不需要
rewrite_log on，除非调试阶段需查日志。
路径重写 + 反向代理
适用于前端统一入口、API 路径标准化等需求。
例如把 /api/v1/xxx 重写为 /v1/xxx 后代理到后端：
location /api/ {
rewrite ^/api/(.*)$ /$1 break;
proxy_pass http://backend_server;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
✅ 关键点：
-
rewrite ... break：改完路径后停止当前 location 内其他 rewrite 规则，继续执行 proxy_pass； -
break不重新匹配 location，last会重新 search，容易引发循环（尤其配合location /时）； -
proxy_pass末尾是否带/很关键：-
proxy_pass http://backend/;→ 剥掉/api/，发/v1/xxx； -
proxy_pass http://backend;→ 发/api/v1/xxx（不推荐）。
-
条件化重定向（按变量或规则）
比如只对非移动端用户跳转，或屏蔽特定路径：
# 屏蔽 /admin 路径，返回 403
location = /admin {
return 403;
}
# 根据 User-Agent 重定向到 mobile 站点
if ($http_user_agent ~* "(Mobile|Android|iPhone)") {
rewrite ^(.*)$ https://m.example.com$1 permanent;
}
# 防止空 host 头攻击，强制跳转到合法域名
if ($host !~ ^(example\.com|www\.example\.com)$) {
return 301 https://example.com$request_uri;
}
⚠️ 注意：
-
if在 location 外可用，但尽量少用（Nginx 官方不推荐在 location 内嵌 if）； -
return优先级高于 rewrite，执行后立即终止； - 正则中
~*表示忽略大小写匹配； -
$host是请求头 Host 字段，$http_user_agent是 UA 字符串。
调试与验证要点
- 开启 rewrite 日志辅助排查（临时）：
rewrite_log on; # 需配合 error_log notice; error_log /var/log/nginx/error.log notice;
- 测试时用
curl -I查看响应头Location和状态码； - 修改配置后务必
nginx -t && nginx -s reload； - 浏览器缓存 301 很顽固，测试建议用隐身窗口或加随机参数（如
?t=123）。
不复杂但容易忽略细节，关键是分清你要的是“用户看到的跳转”还是“后端收到的路径”，再选对指令和 flag。
