迁移与常见问题

从旧实现迁移

当前仓库已修正导航和缓存行为，但不代表这些改动已经发布到 npm。

• push/replace 返回真实 Promise：使用 await，并处理失败结果和拒绝。
• addRouter 同步抛出配置错误，不再吞掉错误返回 false。
• beforeEach 返回注销函数，支持异步守卫。确认保护不再依赖用户注册 beforeEach。
• 取消导航不会写入新动态缓存，也不会关闭离开保护。
• reloadRoutes 预检查整个配置和父子依赖；缺少父路由不再在批量装载中静默回退。
• 动态路由与持久化清单分离，单缓存模式也能清除所有已注册动态页面。
• Pinia 已显式声明为 peer dependency。

旧缓存可能含静态路由、旧模板键或失效的父关系。升级时清理旧缓存，或按账号和配置版本迁移。

页面刷新后 404

检查是否配置持久化，并在创建 router 前设置回调；确认恢复数据中的模板键和父路由有效。单缓存无法自动补足动态父路由树。

同模板输入没有保留

检查组件是否用懒加载模板、route meta 是否标记 keepAlive、是否在成功导航后维护名单，以及 <keep-alive :include> 是否绑定同一 store。名单匹配的是组件名称。

路径参数被丢弃

params 必须对应路径中的 :参数名。例如 { params: { id: '1' } } 需要 /report/:id；普通筛选条件请使用 query。

是否已具备全面生产保证

核心实现有自动化测试与 Chromium 开发环境验证。跨浏览器、生产构建浏览器执行、存储异常、并发导航和关闭标签页行为仍应在具体项目中验证。覆盖率不能替代场景验证。