如何利用 rewrite 指令实现静态资源版本的平滑过渡与路径重构-Nginx-PHP中文网

rewrite实现静态资源平滑过渡的核心是不改变用户URL而内部重写路径，适用于路径结构调整与版本目录切换，需在匹配location中配置，推荐使用last标志进行内部重写，配合try_files提供兜底保障。

如何利用 rewrite 指令实现静态资源版本的平滑过渡与路径重构

用 rewrite 指令实现静态资源版本的平滑过渡，核心在于**不改变用户访问 URL 的前提下，内部重写请求路径到新版资源位置**，从而避免前端代码批量修改、CDN 缓存失效或页面报错。它适用于路径结构调整（如从 /dist/css/ 移至 /css/）、版本目录切换（如 /v1/ → /v2/）等场景，与 try_files 的“回退查找”形成互补：前者是主动改写，后者是被动兜底。

明确 rewrite 触发条件与作用范围

rewrite 必须在能匹配原始请求路径的 location 块或 server 级别中配置，且仅对 URI 路径生效（不处理查询参数）。常见适用情形包括：

旧版构建产物统一放在 /dist/ 下，新版已移至根目录，但 HTML 中仍大量引用 /dist/main.js
历史版本部署在 /static/v1/，新版本发布到 /static/v2/，需临时将所有 v1 请求导向 v2
CDN 或反向代理层需标准化路径前缀（如统一去除 /legacy/）

基础 rewrite 语法与安全重定向控制

基本格式为：rewrite [flag];。关键点在于 flag 的选择：

last：内部重写，Nginx 会用新 URI 重新匹配 location，适合路径映射（推荐用于静态资源迁移）
break：停止当前 location 内后续 rewrite，并不再匹配新 URI，适合简单路径截断
redirect 或 permanent：触发 302/301 重定向——这会暴露路径变更、中断缓存、增加跳转延迟，静态资源平滑过渡中应避免使用

示例：将所有 /dist/ 开头的请求，内部重写为去掉 /dist 前缀的路径

location /dist/ {
rewrite ^/dist/(.*)$ /$1 last;
}

结合正则提取与动态路径生成

当新旧路径存在结构差异（如哈希文件名、目录层级变化），需用正则捕获关键字段再重组：

旧路径：/static/v1/js/app.a1b2c3.js → 新路径：/js/app.js（去掉版本号和哈希）
配置：rewrite ^/static/v1/(js|css|img)/(.+)\.[a-f0-9]{6,}\.(js|css|png|jpg|gif)$ /$1/$2.$3 last;
说明：捕获分组 $1（目录类型）、$2（文件名主体）、$3（后缀），拼出干净路径

该方式可适配 Webpack/Rollup 的 contenthash 输出，无需等待前端全部更新引用。