如何利用 rewrite ^/(.*) 实现请求路径的全量平滑迁移实战-Nginx-PHP中文网

^/(.*) 是高风险全量重写模式，需通过 location 精确限定范围、try_files 提供容错、break 防止循环，结合排除静态资源与 api、设置 fallback 和路径隔离，才能实现安全平滑迁移。

如何利用 rewrite ^/(.*) 实现请求路径的全量平滑迁移实战

rewrite ^/(.*) 是一个看似简单、实则高风险的全量路径重写模式。它本身不是“开箱即用”的迁移方案，而是一把双刃剑——用对了能快速接管流量，用错了会引发循环重定向、静态资源丢失或后端路由错乱。真正的平滑迁移，关键不在正则本身，而在如何约束它、配合什么指令、放在哪里执行。

必须明确：^/(.*) 不等于“全部重写”，而是“匹配全部但需精准控制”

这个正则会捕获根路径及之后所有内容（如 `/api/user` → `$1 = api/user`，`/css/app.css` → `$1 = css/app.css`），但它不区分资源类型、不感知版本、不判断是否存在。直接写 `rewrite ^/(.*) /new/$1 last;` 极易导致： - 静态文件被错误重写，`/favicon.ico` 变成 `/new/favicon.ico` 后 404 - 已经在 `/new/` 下的请求又被重写，陷入无限循环 - 查询参数（如 `?t=123`）虽自动保留，但若新路径不支持，后端可能忽略或报错

所以，不能裸用，必须加条件、设范围、配兜底。

实战中推荐的三层防护式写法

不是单条 rewrite 解决问题，而是组合 location + rewrite + try_files 构建安全迁移链：

第一层：用 location 精确圈定要迁移的路径范围
比如只迁移旧版前端入口，不碰 API 和静态资源：

location / {
    # 排除已知静态资源后缀和 API 前缀
    if ($request_uri ~* "\.(js|css|png|jpg|gif|ico|svg|woff2?)$") {
        break;
    }
    if ($request_uri ~* "^/api/") {
        break;
    }
    # 其余路径才进入 rewrite
    rewrite ^/(.*)$ /new/$1 last;
}

第二层：用 try_files 提供“找不到就回退”的容错能力
在 /new/ location 中配置，确保即使重写后文件不存在，也能 fallback 到旧路径或 index.html（适合 SPA）：
```
location /new/ {
    alias /var/www/new/;
    try_files $uri $uri/ /new/index.html;
}
```
第三层：用 break 替代 last 防止 location 误跳（尤其在 proxy_pass 场景）
若你是在反向代理块中做迁移（比如把所有非 /v2/ 请求转给 v2 服务），应避免 last 触发二次匹配：
```
location / {
    rewrite ^/(?!v2/)(.*)$ /v2/$1 break;
    proxy_pass http://v2_backend;
}
```

典型迁移场景与对应 rewrite 写法

不同目标，正则写法和 flag 选择完全不同：

单页应用（SPA）路由接管（如 Vue/React）
所有非静态资源请求都指向 index.html：

location / {
    try_files $uri $uri/ @rewrites;
}
location @rewrites {
    rewrite ^(.*)$ /index.html last;
}

整站路径前缀迁移（如 / → /legacy/ 临时保留）
仅对原根路径下内容重写，排除已有前缀：

location = / { rewrite ^ /legacy/ permanent; }
location / {
    rewrite ^/(?!(legacy|api|static)/)(.*)$ /legacy/$1 last;
}

灰度迁移：按 Cookie 或 Header 分流
结合 map + if（注意：if 仅限于简单变量判断，不可嵌套复杂逻辑）：

map $http_x_version $target_prefix {
    "v2" "/v2/";
    default "/";
}
location / {
    rewrite ^/(.*)$ $target_prefix$1 break;
    proxy_pass http://backend;
}

务必避开的三个坑

这些错误在真实环境中高频出现，且排查困难：

在 server 块顶层直接写 rewrite ^/(.*)
会导致所有请求（包括健康检查、.well-known、Let’s Encrypt 验证）都被重写，服务瞬间不可用。
用 permanent/redirect 做“平滑迁移”
301 会强制浏览器跳转、清空本地缓存、暴露新路径，违背“用户无感”原则；平滑迁移必须用 last 或 break 实现内部重写。
忽略 root / alias 与 rewrite 路径拼接关系
rewrite ^/a/(.*)$ /b/$1 last; + root /var/www; → 实际查找 /var/www/b/file.js；
若用 alias /var/www/a/;，则 rewrite 后路径会相对于 alias 目录拼接，极易出错。建议统一用 root + location 显式隔离。