Vue Router 4 迁移指南：从 Vue 2 到 Vue 3 的平滑过渡

前言

随着 Vue 3 的发布，Vue Router 也迎来了重大更新版本 v4。虽然大部分 API 保持不变，但仍有一些破坏性变更需要注意。本文将全面解析 Vue Router 从 v3 到 v4 的迁移要点，帮助开发者顺利完成升级。

核心变更概览

1. 创建路由器的变化

Vue Router 不再是一个类，而是一组函数：

// 旧版写法
import Router from 'vue-router'
const router = new Router({...})

// 新版写法
import { createRouter } from 'vue-router'
const router = createRouter({...})

2. 路由模式配置重构

mode 选项被更灵活的 history 选项取代：

import { createWebHistory, createWebHashHistory } from 'vue-router'

createRouter({
  // 替换 mode: 'history'
  history: createWebHistory(),
  // 替换 mode: 'hash'
  // history: createWebHashHistory(),
  routes: []
})

设计考量：这种变化支持了更好的 tree shaking，也便于实现自定义历史记录方案。

3. 基础路径(base)配置调整

base 配置现在作为历史记录函数的参数：

createRouter({
  history: createWebHistory('/base/'),
  routes: []
})

路由匹配相关变更

1. 通配符路由的新写法

不再支持 * 通配符，改为使用参数加正则表达式：

{
  path: '/:pathMatch(.*)*', 
  name: 'not-found', 
  component: NotFound
}

最佳实践：如果需要通过名称导航到404路由，必须使用 * 后缀以确保参数正确编码。

2. 精确匹配(exact)属性移除

exact 属性已被移除，路由激活匹配逻辑已优化：

• 现在基于路由记录而非生成的路由位置对象
• 仅匹配 path 部分，忽略 query 和 hash

导航相关变更

1. 导航守卫的异步特性

所有导航现在都是异步的，包括初始导航：

app.use(router)
router.isReady().then(() => app.mount('#app'))

注意事项：如果使用过渡效果，必须等待路由就绪后再挂载应用，否则会出现初始过渡效果。

2. 导航API更新

• onReady 替换为返回 Promise 的 isReady
• router.match 和 router.resolve 合并为新的 resolve 方法
• getMatchedComponents 方法移除，可通过 currentRoute.value.matched 获取

组件相关变更

1. RouterView 的插槽语法

过渡和缓存组件现在必须通过 v-slot API 使用：

<router-view v-slot="{ Component }">
  <transition>
    <keep-alive>
      <component :is="Component" />
    </keep-alive>
  </transition>
</router-view>

2. RouterLink 的属性调整

• 移除 append 属性：可通过全局方法实现
• 移除 event 和 tag 属性：使用 v-slot API 完全自定义
• 移除 exact 属性：匹配逻辑已优化

其他重要变更

1. 路由位置对象变化

• currentRoute 现在是 ref 对象，访问需要 .value
• 移除 parent 属性，通过 matched 数组访问父路由
• 状态管理使用 history.state，手动调用 history API 需注意

2. 参数编码一致性

params、query 和 hash 的解码行为现在保持一致：

• path 和 fullPath 保持编码状态
• hash 自动解码便于直接使用

迁移建议步骤

1. 基础升级：先更新创建路由器和模式配置
2. 路由调整：处理通配符路由和参数变化
3. 导航改造：更新异步导航相关代码
4. 组件适配：调整 RouterView 和 RouterLink 的使用
5. 全面测试：特别注意边界情况和错误处理

结语

Vue Router 4 的这些变更虽然带来了一些迁移成本，但整体设计更加现代化和一致。理解这些变化背后的设计理念，能够帮助开发者更好地适应新版本，并充分利用其改进特性。建议在迁移过程中参考官方文档和本文要点，逐步完成升级工作。