Vue Router 5.4.0：hash 不再解码，重定向不再继承 params/query/hash

Vue Router v5.4.0 于 2026-10-07 发布，仓库：。

这个版本真正会打断现有代码的，主要是几处默认行为变化，而不是新增 API：hash 段不再解码，重定向不再隐式继承 params/query/hash，带默认值的 query 参数在 push 时可以省略，滚动恢复的默认行为也有调整。下面按影响面从大到小排列。

hash 不再解码，只做保护性编码（#2760）

Never decode the hash, protect-only encoding — #2760。读取 route.hash（以及 router.resolve() 的结果）时，拿到的是保持百分号编码的原字符串，不再返回解码后的值；编码只在写入侧做必要保护。

受影响的是所有对 hash 做字符串比较、正则匹配，或把 hash 片段直接当参数用的代码。遇到 %20、中文、嵌套编码时，结果与旧版本不同。

自查：搜索 route.hash、$route.hash 和围绕 hash 的 decodeURIComponent；把断言改为「编码后的原值」，或者统一在一处解码，避免下游各自处理。

definePage 的 hash 参数

这一组改动包括：Extract hash params with definePage、Configure required and default hash params、Make hash params optional and nullable、Exclude defaults from required hash params、Align hash parameter parsing with queries、Keep last hash param instead of throwing。

hash 参数的解析规则向 query 对齐：参数可选、可空，支持 required 与 default；声明了 default 的参数不会进入 required 集合；出现重复 hash 参数时保留最后一个，不再抛错。

受影响的是依赖「hash 参数必填」或「重复 hash 参数报错」的写法。自查 definePage 里的 hash 声明，尤其别把 required 和 default 写在同一参数上。

重定向不再继承 params/query/hash

Do not inherit params, query, or hash on redirects。redirect 返回字符串或对象时，目标路由不再自动带上来源路由的 params、query、hash。

典型受影响场景是「登录后跳回原页面」这类依赖隐式继承查询串的逻辑，升级后会丢参数。自查：搜索所有 redirect，凡是期望保留来源信息的，改成函数式 redirect，显式把 to.params、to.query、to.hash 传过去。这条还要和 Resolve experimental guard redirects against target on history navigation 一起看——experimental 守卫里的重定向现在是针对目标路由解析的。

query 默认值：push 可省略，required 不能与 default 并存

Make query params with a default optional on push：声明了默认值的 query 参数，在 router.push({ query }) 时可以省略，省略即使用默认值。Disallow required with a default for query params：同一个 query 参数不能既 required 又给 default。

影响两处：以前为了通过必填校验、每次 push 都显式带上的默认值字段，现在可以不传；反过来，required + default 的组合不再被接受。自查：列出所有 query 声明检查组合，再把 push 里「只为填默认值」的字段清掉，确认解析结果一致。

滚动位置：useScrollRestoration、onRouteRendered 与默认恢复

• UseScrollRestoration and onRouteRendered — @posva #2805
• router: Restore hashes and top by default
• history: Invalidate obsolete scroll positions — @posva and @liuly0322 #2814

router 默认恢复 hash 定位与 top；useScrollRestoration 和 onRouteRendered 提供组合式接口，用来接管滚动恢复和「路由渲染完成」的时机；#2814 让过期的滚动位置失效，避免异步渲染完成后跳回旧位置。

受影响的是自定义了 scrollBehavior、或历史上依赖旧滚动时机的页面。自查三条路径：hash 跳转、前进/后退、异步组件加载，逐条核对最终滚动位置；已有自定义滚动恢复逻辑的，确认不会和新的默认行为叠加。

其他变更

• Breaking（experimental）：Normalize query values to arrays — #2824。开启 experimental 的项目，query 值统一为数组，按单值处理的代码需要改。
• Accept a prebuilt matcher in createRouter — @danielroe #2804，SSR 与测试场景可以复用已构建的 matcher。
• Allow custom regexp for path params in definePage — #2822。
• experimental: Warn about legacy optional param removal — #2818、Diagnose experimental beforeEnter migration，开启 experimental 后会看到新的迁移警告。
• unplugin: Sanitize named view in definePage import — @giaBaoJS #2809、Keep hex character codes in param segments regexp — @kwy404 #2811、experimental: Keep declared case of static prefix in MatcherPatternPathStar.build() — @contactjawad #2798。
• 性能：unplugin: Cache merged route overrides — #2821。

更早版本留下的行为，升级时一并确认

• v5.3.0（2026-08-27）：scroll 根据 history.scrollRestoration 跳过滚动计算；移除 visibilitychange 监听，避免 Edge 抢焦点（#2704）。
• v5.1.0（2026-05-28）：query 参数格式非法时发运行时警告；过滤非法 query 参数，而不是让匹配失败。
• v5.0.7（2026-05-13）：query 对象使用 Object.create(null) 防原型污染（#2661）；resolve 时省略空的可选参数（#2434）。

自查清单

1. 搜 hash：读取处是否假设已解码；手写 hash 拼接处是否与保护性编码冲突。
2. 搜 redirect：是否存在依赖隐式继承 params/query/hash 的写法。
3. 检查 definePage：hash 参数是否 required 与 default 并存；是否依赖重复参数抛错。
4. 检查 query 声明：required 与 default 是否同时出现；push 中哪些默认值字段可以省略。
5. 开启 experimental 的项目：#2824 的 query 数组化、#2818 的可选参数移除警告、beforeEnter 迁移诊断。
6. 滚动：hash 跳转、前进/后退、异步组件加载三条路径各走一遍。