Vue Router v5.4.0：预构建 matcher、滚动恢复 API 落地，实验特性下 query 一律归一为数组
Vue Router v5.4.0 于 2026-10-07 发布。这次更新里有一项破坏性变更、若干实验性功能，以及一批针对 hash 参数和路由匹配器的修复。
- 仓库：https://github.com/vuejs/router
- 官网：https://router.vuejs.org
- CHANGELOG：https://github.com/vuejs/router/blob/main/packages/router/CHANGELOG.md
破坏性变更：实验模式下 query 值统一为数组
在实验性（experimental）模式下，query 参数的值现在会被统一规范化为数组。该变更由 @posva 在 #2824 中提交（commit f1fbc）。
也就是说，在新的实验性 router 里，所有 query 值默认都是数组，这样类型检查会简单一些。想拿单个值仍然走 param parsers，这一块没有变化。依赖 query.xxx 直接是字符串的代码需要一并调整。
新特性
- createRouter 支持传入预构建的 matcher：由 @danielroe 在 #2804 中实现（commit 9de96），可以复用或自定义路由匹配器。
- 新增 useScrollRestoration 与 onRouteRendered：由 @posva 在 #2805 中实现（commit e3dde），滚动位置恢复和「路由渲染完成」时机现在有官方 API。
- beforeEnter 迁移诊断：用于识别实验性 beforeEnter 的迁移问题（commit b695c）。
- 旧式可选参数移除警告（#2818，commit c2f92）。
- 通过 definePage 提取 hash 参数（commit dbf2d）。
- 支持配置必填与默认 hash 参数（commit cef5c）。
- 不再对 hash 解码，只做保护性编码（#2760，commit aca2c）。
- definePage 中的路径参数支持自定义正则（#2822，commit 3a192）。
- router 默认恢复 hash 与页面顶部位置（commit 7c385）。
Bug 修复
- 历史导航中，针对目标解析实验性守卫重定向（commit 2c5fb）。
- 实验性：
MatcherPatternPathStar.build()保留静态前缀的声明大小写（#2798，commit 4dc6b）。 - 使 hash 参数可选且可为空（commit d9a4c）。
- 从必填 hash 参数中排除默认值（commit 346e2）。
- 使 hash 参数解析与 query 保持一致（commit cf251）。
- 保留最后一个 hash 参数，而不是抛异常（commit d1e8a）。
- 禁止 query 参数同时设置必填与默认值（commit f60e9）。
- push 时，带默认值的 query 参数视为可选（commit fb604）。
- 重定向时不再继承 params、query 或 hash（commit 02a92）。
- history：使过期的滚动位置失效（#2814，commit 071f1）。
- unplugin：清理 definePage 导入中的命名视图（#2809，commit 0711d）。
- 在参数段正则中保留十六进制字符编码（#2811，commit 07663）。
性能
- unplugin：缓存合并后的路由覆盖（#2821，commit 732b723）。
升级建议
v5.4.0 的主要变化集中在三处：createRouter 接受预构建 matcher、新增 useScrollRestoration 与 onRouteRendered，以及围绕 hash 参数的一系列实验性改进。
由于实验模式下 query 归一化为数组属于破坏性变更，使用实验特性的项目在升级前先读一遍对应的 commit 说明，确认代码里没有对 query 值类型的隐式假设，再动手升级。