nginx路径迁移需零感知、零中断、免前端配合，通过location分层、rewrite+try_files容错、map动态路由及可观测机制实现可验证可回退。
请求路径配置的维护与平滑迁移，核心是不让用户感知变更、不中断现有服务、不依赖前端配合，同时支持渐进验证和秒级回退。Nginx 本身不提供“发布系统”，但通过 location 分层、rewrite 控制、try_files 容错和 map 动态路由组合，就能把路径变更变成一次可观察、可收敛、可逆的操作。
用 location 精确圈定迁移范围，避免误伤
路径迁移最怕“一刀切”——比如直接 rewrite ^/.*，结果连 /favicon.ico 和 /healthz 都被重写。应优先用 location 匹配明确前缀或特征，再在内部做逻辑判断：
- 只对业务入口路径迁移：location / { ... }，但内部用 if 排除静态资源和 API 路径
- 按版本前缀隔离：location /v1/ { proxy_pass http://old_backend; }，location /v2/ { proxy_pass http://new_backend; }
- 用正则命名捕获控制粒度：location ~ ^/(app|admin)/(.*)$ { rewrite ^/(app|admin)/(.*)$ /new/$1/$2 last; }
rewrite + try_files 构建安全重写链
rewrite 不是终点，而是中间环节；try_files 才是兜底关键。两者必须配合使用，否则容易 404 或循环重定向：
- rewrite 使用 last 时，确保目标 location 存在且能处理新路径；若在 proxy_pass 块中，改用 break 防止二次匹配
- try_files 至少列出两个 fallback：$uri /index.html =404，尤其对 SPA 应用，保证路由丢失时仍可加载主入口
- 静态资源路径变更后，root 或 alias 必须同步更新，且目录权限、文件存在性需提前验证
借助 map 实现环境/流量维度的动态路径路由
当不同用户、域名或参数需要走不同路径时，硬编码 location 不可持续。map 指令能将决策逻辑前置，提升可读性和扩展性：
- 按域名区分资源根路径：map $host $static_root { test.example.com "/data/static-test"; default "/data/static-prod"; }，再在 location 中 root $static_root;
- 按请求头灰度：map $http_x_release_stage $backend { "beta" "new_upstream"; default "old_upstream"; }，配合 proxy_pass http://$backend;
- 注意 map 必须定义在 http 块顶层，不能嵌套在 server 或 location 内
配套可观测与收敛验证机制
平滑不是“没报错就算成功”，而是要确认真实流量已按预期走向新路径：
- 在关键 location 中添加自定义日志：log_format migrate '$time_local $uri → $request_uri $status';，记录原始请求与最终处理路径
- 响应头暴露路由信息：add_header X-Route-Source "v2"; add_header X-Static-Root "$static_root"; 方便前端或监控采集
- 结合 access_log 和 error_log，统计 404、502 出现频次与 URI 分布，快速定位缺失资源或配置遗漏点
