nginx api路由重写核心是路径解耦与透明转发，通过rewrite指令改写uri、proxy_pass反向代理，需区分break/last、避免重写循环、正确配置proxy_pass结尾及正则大小写。
Nginx 做 API 路由重写，核心是让外部请求路径与后端服务实际接口路径解耦。比如用户访问 /user/123，后端真实接口却是 /api/v1/users/123，这时就需要用 rewrite 指令做路径转换，并配合 proxy_pass 完成反向代理。
关键点不是单纯“跳转”，而是内部路径改写 + 透明转发 —— 浏览器地址栏不变，后端收到的是修正后的路径。
用 rewrite + proxy_pass 去掉前缀（最常用）
适合统一入口、需剥离公共路径的场景。例如所有 API 请求带 /api 前缀，但后端服务不认这个前缀：
location /api/ {
rewrite ^/api/(.*)$ /$1 break;
proxy_pass http://backend-service;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
-
^/api/(.*)$匹配/api/xxx，捕获xxx部分 -
/$1把它变成/xxx -
break表示改完就停，不再执行其他 rewrite，直接用新 URI 走proxy_pass - 注意：
proxy_pass结尾不能加/，否则会拼接两次路径（Nginx 会把/api/xxx整体当路径转发过去）
✅ 正确：
proxy_pass http://backend-service;→ 转发/xxx
❌ 错误：proxy_pass http://backend-service/;→ 可能变成http://backend-service//xxx
用 rewrite + proxy_pass 替换路径结构
适合接口路径重构或兼容旧版调用。例如前端仍调 /v1/user/get，但后端已迁到 /users/{id}：
location ~ ^/v1/user/get$ {
rewrite ^/v1/user/get$ /users?method=get last;
proxy_pass http://backend-service;
}
-
~表示正则匹配，支持更灵活的规则 -
last表示重写后，Nginx 会重新匹配 location（比如可能进入另一个location /users块） -
$1、$2可引用括号捕获的内容，比如^/v1/user/(\d+)$→/users/$1
Ingress 中配置（K8s 环境）
如果用 Kubernetes Ingress（Nginx Ingress Controller），不用写原生 Nginx 配置，改用 annotation：
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: api-ingress
annotations:
nginx.ingress.kubernetes.io/use-regex: "true"
nginx.ingress.kubernetes.io/rewrite-target: /api/v1/$1
spec:
ingressClassName: nginx
rules:
- host: api.example.com
http:
paths:
- path: /user/(.*)
pathType: Prefix
backend:
service:
name: user-svc
port:
number: 8080
- 外部请求
/user/profile→ 内部转发为/api/v1/profile -
use-regex: "true"启用正则支持 -
rewrite-target是目标路径，$1对应path中(.*)的捕获内容
注意事项和易错点
-
last和break别混用：last会重启 location 匹配，适合需要再进某个 location 块的场景；break就地终止，适合简单路径替换后直连后端。 -
避免重写循环：比如
rewrite /a /b; rewrite /b /a;，Nginx 默认最多执行 10 次 rewrite，超限返回 500。 -
proxy_pass和rewrite的顺序不能颠倒：必须先rewrite，再proxy_pass，否则改写无效。 -
大小写敏感：默认正则区分大小写，如需忽略，用
~*（如location ~* ^/API/）。
不复杂但容易忽略细节。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
