rewrite是Nginx API网关中路径重写的常用工具，用于统一入口、隐藏后端路径等，但需注意执行时机、正则匹配逻辑及break/last区别，避免404、循环重定向或参数丢失。
在 Nginx 作为 API 网关使用时，rewrite 指令是路径重写最常用、最灵活的工具之一。它能帮你统一入口、隐藏后端真实路径、兼容旧版接口、实现版本路由等，但用错容易导致 404、循环重定向或参数丢失。
理解 rewrite 的执行时机和匹配逻辑
rewrite 在 Nginx 的 server 或 location 块中生效，按书写顺序逐条执行（除非加 last 或 break 控制流程）。它匹配的是 请求 URI 的路径部分（不含 query string），且默认不区分大小写（除非加 i 标志）。
常见误区：以为 rewrite 能直接操作 query string —— 实际上它只改 path；想改参数得配合 set + add_header 或用 return 重定向带新参数。
典型场景与安全写法
-
API 版本前缀剥离：把
/v1/users重写为/users透传给后端rewrite ^/v[0-9]+/(.*)$ /$1 break;
注意用break防止后续 location 再次匹配，避免重复处理。 -
统一入口代理到不同服务：如将
/auth/xxx→auth-svc/xxxlocation /auth/ { rewrite ^/auth/(.*)$ /$1 break; proxy_pass http://auth-svc; }
这里必须用break，否则 proxy_pass 的末尾斜杠逻辑会出错。 -
强制跳转并保留参数：旧路径
/api/user?id=123→ 新路径/v2/users?id=123rewrite ^/api/user(.*)$ /v2/users$1? permanent;?结尾可清空原始 query，但这里保留$1（含 ? 及后续），确保参数不丢。
避坑要点：别让 rewrite 成为线上故障源
- 永远在测试环境验证正则——用
curl -I查看响应头中的Location，确认跳转是否符合预期 - 避免无终止条件的 rewrite 循环，例如：
rewrite /foo /bar;+rewrite /bar /foo;，Nginx 默认最多执行 10 次就返回 500 - location 中使用
rewrite ... last会重新发起内部请求，触发新一轮 location 匹配；用break则只改 path，继续当前 location 流程 - 如果后端依赖原始路径（比如做权限校验），不要盲目 rewrite，可改用
proxy_set_header X-Original-URI $request_uri;透传原始值
配合 map 实现更清晰的路径映射
当 rewrite 规则超过 3 条、逻辑开始混乱时，建议改用 map 指令预定义路径映射关系，提升可读性和维护性：
map $uri $upstream_path {
~^/legacy/login$ /v1/auth/login;
~^/users/(\d+)$ /v2/profile/$1;
~^/orders.*$ /v2/checkout/orders;
default $uri;
}
location / {
proxy_pass http://backend$upstream_path;
}
这种方式把“判断逻辑”和“代理动作”分离，比堆砌 rewrite 更易排查和扩展。
