Vue Router 迁移指南

欢迎来到 Vue Router 迁移指南！🚀 这里汇集了从旧版本升级到最新版本的所有重要信息和步骤，让你的迁移过程更加顺畅。

📋 迁移概览

Vue Router 的版本迁移主要涉及以下方面：

版本	主要变化	迁移难度
v3 → v4	重大 API 重构	⭐⭐⭐⭐⭐
v4 → v5	渐进式改进	⭐⭐

🔄 从 Vue Router v3 迁移到 v4

这是最大的一次迁移，涉及大量 API 变化和概念更新。

核心变化速览

1. 路由创建方式变化

v3 写法：

const router = new VueRouter({
  mode: 'history',
  routes: [...]
})

v4 写法：

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

const router = createRouter({
  history: createWebHistory(),
  routes: [...]
})

2. 路由组件访问方式

v3 写法：

// Options API
this.$router
this.$route

// Composition API (需要额外安装)
import { useRouter, useRoute } from 'vue-router'

v4 写法：

// Composition API (内置支持)
import { useRouter, useRoute } from 'vue-router'

const router = useRouter()
const route = useRoute()

详细迁移步骤

步骤 1：更新依赖

# 卸载旧版本
npm uninstall vue-router

# 安装新版本
npm install vue-router@4

步骤 2：更新路由配置

// 之前 (v3)
import VueRouter from 'vue-router'

const router = new VueRouter({
  mode: 'history',
  base: process.env.BASE_URL,
  routes
})

// 之后 (v4)
import { createRouter, createWebHistory } from 'vue-router'

const router = createRouter({
  history: createWebHistory(process.env.BASE_URL),
  routes
})

步骤 3：更新组件中的路由使用

<!-- 之前 (v3) -->
<template>
  <button @click="$router.push('/home')">首页</button>
</template>

<script>
export default {
  methods: {
    goBack() {
      this.$router.go(-1)
    }
  }
}
</script>

<!-- 之后 (v4) -->
<template>
  <button @click="router.push('/home')">首页</button>
</template>

<script setup>
import { useRouter } from 'vue-router'

const router = useRouter()

const goBack = () => {
  router.go(-1)
}
</script>

🔄 从 Vue Router v4 迁移到 v5

v5 版本主要是优化和改进，迁移相对简单。

主要改进

1. 更好的 TypeScript 支持

// v5 提供了更精确的类型推断
const router = useRouter()
router.push('/user/123') // 类型安全的路由跳转

2. 性能优化

• 更小的包体积
• 更快的路由匹配
• 改进的懒加载机制

迁移步骤

步骤 1：更新依赖

npm install vue-router@5

步骤 2：检查破坏性变化

查阅官方发布说明，检查是否有影响你项目的破坏性变化。

🛠️ 迁移工具和技巧

自动迁移工具

Vue 官方提供了迁移助手工具：

npx @vue/compat@latest --router

手动迁移检查清单

• [ ] 更新 package.json 中的依赖版本
• [ ] 替换 new VueRouter() 为 createRouter()
• [ ] 更新历史模式配置
• [ ] 检查并更新导航守卫
• [ ] 更新组件中的路由访问方式
• [ ] 测试所有路由功能
• [ ] 更新 TypeScript 类型定义（如果使用）

🚨 常见问题解决

问题 1：路由跳转后页面不更新

解决方案： 检查是否正确地使用了 useRouter() 和 useRoute()

问题 2：TypeScript 类型错误

解决方案： 更新类型导入和确保正确配置路由类型

问题 3：导航守卫不工作

解决方案： 检查守卫函数的签名和返回值

📚 更多资源

• 官方迁移指南
• 破坏性变化列表
• 社区迁移经验分享

💡 专业建议：建议先在开发环境进行迁移测试，确保所有功能正常后再部署到生产环境。