/#/order/123 迁到 history 模式:服务端 rewrite 为什么无效,怎么做两段式迁移
先说结论。哈希片段永远不进 HTTP 请求行。浏览器发请求的时候只发 GET /,#/order/123 是浏览器自己保留的文档内定位信息。所以 Nginx 的 try_files、Apache 的 mod_rewrite、CDN 的边缘规则、边缘函数,全都拿不到这段字符串——它们收到的是已经被裁掉 fragment 的 URL。没有任何服务端规则能把 /#/order/123 变成 /order/123。
能做的只有一件事:index.html 返回后、路由实例解析首次路由之前,前端 JS 读一次 location.hash,把它拼到 location.pathname 上,再 history.replaceState 覆盖当前历史记录。另一条路是接受老链接全部失效——二维码、公众号文章、短信、邮件模板里的 /#/xxx 不会因为你改了路由就跟着改。
curl 测不出 hash 迁移
curl -I 'https://example.com/#/order/123' 和 curl -I https://example.com/ 打出去的请求行完全一样:
GET / HTTP/1.1
curl 会自行丢弃 fragment,浏览器也一样。所以用 curl 测不了 hash 迁移,只能在浏览器里手动验证,或者用 headless 浏览器跑一条断言。服务端 access log 同理:hash 模式下不管用户点进哪个“页面”,日志里从头到尾只有一条 GET /。
迁移代码:放在 router 实例化之前执行
这段代码要放在 createApp、createRouter 之前,早于首次路由解析,让 router 一开始读到的就已经是清洗后的 URL。
const h = location.hash
if (h.startsWith('#/')) {
const target = location.pathname + h.slice(1)
history.replaceState(history.state, '', target)
}
replaceState 不是可选项。用 location.replace 会往历史记录里多压一层,用户点返回会回到 hash URL,又被这段代码搬回来,等于永远退不出这一页。
history.state 原样透传,是因为有些场景首屏加载前已经有 state 被写入(比如服务端注入的初始数据),传 null 会直接抹掉。
hash 里带 query 的合并顺序
hash 模式下 query 常被写在 # 后面:/#/order/123?tab=2。如果老链接本身还带 path 级 query,直接拼会得到错误路径:
/app?from=sms#/order/123
→ /app?from=sms/order/123 // 坏路径
正确做法是先把 hash 按第一个 ? 拆成 path 和 query 两段,再把 hash 里的 query 与 location.search 合并。哪一部分优先需要自己定一个规则并写进文档,这里建议 hash 内的 query 优先,因为那才是用户在当前链接里明确请求的参数。
const h = location.hash
if (h.startsWith('#/')) {
const q = h.indexOf('?')
const hashPath = q === -1 ? h.slice(1) : h.slice(1, q)
const hashQuery = q === -1 ? '' : h.slice(q + 1)
const merged = new URLSearchParams(location.search)
new URLSearchParams(hashQuery).forEach((v, k) => merged.set(k, v))
const search = merged.toString()
const target = location.pathname.replace(/\/$/, '') + hashPath +
(search ? '?' + search : '')
history.replaceState(history.state, '', target)
}
比第一段多几行,但 query 参数丢一个比多一个更麻烦:页面状态错了,用户看到的是默认 tab,还很难复现。
base 两边必须一致
hash 模式下 base 常常没人配,/app/#/order/123 也能跑,因为 # 后面的内容不参与资源解析。history 模式下 base 变成真路径,必须同时出现在两个地方:Vite 的 base 配置项,以及 createWebHistory(base) 的入参。两边不一致的典型表现是首页能打开、一点导航就白屏或者 assets 404。
Vite 侧可用 base 配置项,或 vite build --base=/my/public/path/;运行时动态拼 URL 要用 import.meta.env.BASE_URL,它在构建时被静态替换,必须原样出现,写成 import.meta.env['BASE_URL'] 不生效。详见 Vite 构建文档 · 公共基础路径。
改 base 是构建期改动,老 hash 链接里的前缀也要一起搬:/app/#/order/123 迁移后应该是 /app/order/123,不是 /order/123。
先清掉源码里的硬跳转
grep -rn "#/" src/ 能把 window.location.href = '/#/login'、``,以及硬编码在 markdown、邮件模板、短信模板里的 hash 链接都揪出来。这些东西切到 history 后不会报错,只是把用户跳到一个不存在、或者语义不对的路由,页面照样渲染,内容却是错的。
按修改成本排一下:模板类最难,它们往往不在仓库里,在 CMS 或第三方后台;其次是 a href;再次是 location.href。迁移时能一并改掉的,不要留给兼容层。
hashchange 监听会静默失效
埋点、滚动恢复、锚点高亮常常挂在 window.addEventListener('hashchange') 上。切到 history 后浏览器不再触发 hashchange:pushState / replaceState 不触发,前进后退触发的是 popstate。不会报错,只是这类功能采集到的数据变少,很难在测试里发现。
改成 router.afterEach 或组件内的 onBeforeRouteUpdate,把同样的逻辑挂上去。发版后盯一下埋点事件量,某个事件掉到接近零基本就是这个问题。
不能按用户比例灰度
URL 的语义是全局的:A 用户发出去的链接 B 用户要能打开,同一条链接今天打开和明天打开要落到同一个页面。所以“10% 用户走 history、90% 用户走 hash”这种做法不成立,同一个 URL 在不同用户那里解析成不同页面。
可行的做法是两段式:
第一段,上线“history 输出 + hash 兼容读”。新生成的链接全是 history 路径;老 hash 链接靠上面那段 replaceState 照样能打开。这一阶段在前端埋点里统计兼容代码的触发次数。
第二段,等兼容触发次数降到零(老链接基本被消费完),删掉 hash 兼容代码。这个观测点只能放在前端——服务端日志里本来就看不到 hash,指望日志里 /#/ 消失是等不到的,它从来没出现过。
file:// 和 Electron 必须留 hash
官方文档写得很明确:应用从 file:// URL 加载(比如 Electron 打包的本地页面)时要用 hash 模式,HTML5 模式无法可靠地改变 file:// 下的路径。被第三方 iframe 或客户端 WebView 以本地文件方式打开的应用同理。
这类场景硬迁过去,pushState 的行为不可靠,轻则地址栏不变、路由状态不同步,重则刷新后落到文件系统的 404。判断标准很直接:这个页面会不会被以本地文件路径打开。会,就留在 hash。
SEO 与 canonical
迁移前,搜索引擎眼里所有页面其实是同一个 URL(/),fragment 不参与索引。迁移后每个路由才是独立 URL,这是迁移动机之一。但已有的外链、公众号文章里的 /#/xxx、已经印出去的二维码改不了,只能靠兼容读兜住。
另一个副作用是兜底回退:配了“所有未匹配路径都返回 index.html”之后,服务端不再返回 404,不存在的路径一律 200 + 首页,搜索引擎会抓取大量内容相似的 URL。服务端能识别路由的,对不存在的路由直接返回真 404;纯静态托管的话,至少让 SPA 通配路由页(path: '/:pathMatch(.*)')返回带 noindex 的 404 页面,别让这些页面进索引。
canonical 跟着走:迁移后每个路由页给出自己的 canonical,指向 history 路径,不要继续指向老的 hash URL。
上线顺序
- 确认 CDN / 网关没有对
/assets/之外的路径做 404 短路。有些平台会用 4xx 错误页改写响应体但保留 404 状态码,SPA 能渲染,但搜索引擎和监控看到的都是 404。 - 改 base(Vite 与
createWebHistory同步),清硬跳转,替换hashchange监听。 - 发版。
- 验证两条链接:一条老 hash 链接(应被
replaceState搬成新路径且页面正确),一条新 history 路径(刷新不 404)。 - 观察兼容触发次数,归零后删兼容代码。