Vue3—— 第 18 篇:Vue 2 到 Vue 3 迁移指南——升级避坑全记录

本篇定位:Vue 2 已于 2023 年 12 月 31 日正式停止维护(EOL)。对于仍在使用 Vue 2 的项目,迁移到 Vue 3 是必然的选择。本篇将系统讲解 Vue 2 到 Vue 3 的所有破坏性变更、迁移工具链、生态升级策略,以及从选项式 API 到组合式 API 的渐进式迁移路径。读完本篇,你将能够制定清晰的迁移计划,有条不紊地完成项目升级。

一、为什么需要迁移?

1.1 Vue 2 的生命周期状态

版本 状态 关键时间点
Vue 2.6 已停止维护 2023年12月31日 EOL
Vue 2.7 维护模式(仅安全修复) 最后一个小版本
Vue 3.x 活跃开发 当前主版本

Vue 2.7("Naruto") 是从 Vue 3 反向移植了重要特性的过渡版本,包括:

  • Composition API 支持
  • <script setup> 语法
  • 新的响应式 API(ref、reactive 等)

如果你还在 Vue 2 上,第一步应该升级到 Vue 2.7,这是迁移到 Vue 3 的"桥梁"。

1.2 迁移的收益

收益 说明
性能提升 更快的渲染速度、更小的包体积
更好的 TypeScript 支持 原生 TS 支持,类型推导更准确
组合式 API 更好的逻辑复用和代码组织
新特性 Teleport、Suspense、多根节点等
生态支持 新库和工具优先支持 Vue 3
安全更新 持续的安全修复

1.3 迁移的挑战

  • 破坏性变更多:全局 API、指令、组件等都有变化
  • 生态依赖升级:Vue Router、Vuex/Pinia、UI 库等需同步升级
  • 代码量大:大型项目需要系统性的迁移计划
  • 学习曲线:组合式 API 需要思维转变

二、迁移前的准备

2.1 评估项目现状

在开始迁移之前,先全面评估项目:

① 依赖清单检查

bash 复制代码
# 查看当前 Vue 版本
npm list vue

# 查看所有依赖
npm list --depth=0

需要关注的依赖:

依赖类型 Vue 2 版本 Vue 3 版本 注意事项
Vue 核心 vue@^2.x vue@^3.x 核心升级
Vue Router vue-router@^3.x vue-router@^4.x 破坏性变更较多
Vuex vuex@^3.x vuex@^4.x 或迁移到 Pinia
UI 库 Vuetify 2.x Vuetify 3.x 破坏性变更极大
UI 库 Element UI Element Plus API 基本兼容
构建工具 Vue CLI Vite 推荐迁移到 Vite

② 代码扫描

使用工具扫描 Vue 2 特有的 API 使用情况:

bash 复制代码
# 使用 vue3-breaking-changes-scanner 扫描
npx vue3-breaking-changes-scanner scan ./src

# 或使用 GoGoCode 进行自动化转换(AST 转换)
npx gogocode -s ./src -t vue2-to-vue3

2.2 制定迁移策略

推荐策略:渐进式迁移,而非"大爆炸"式重写

复制代码
阶段一:升级到 Vue 2.7
    ↓
阶段二:使用迁移构建 (@vue/compat) 运行 Vue 3
    ↓
阶段三:逐个修复兼容性警告
    ↓
阶段四:切换到标准 Vue 3 构建
    ↓
阶段五:逐步迁移到组合式 API(可选)

为什么不推荐一步到位:

  • Vue 2 和 Vue 3 的破坏性变更太多
  • 大型项目一次性重写风险极高
  • 迁移构建允许你在 Vue 3 环境下以 Vue 2 兼容模式运行

三、迁移构建(Migration Build):核心工具

3.1 什么是 @vue/compat?

@vue/compat(即迁移构建)是 Vue 3 的一个特殊构建版本,它在 Vue 3 引擎上提供了 Vue 2 兼容的 API 行为。

核心特性:

  • 默认以 Vue 2 模式运行
  • 对已变更或已弃用的特性发出运行时警告
  • 支持逐组件启用/禁用兼容性
  • 可以直接用于生产环境(有少量性能开销)

3.2 安装与配置

步骤 1:安装依赖

bash 复制代码
# 安装 Vue 3 和迁移构建
npm install vue@^3 @vue/compat

# 升级路由和状态管理
npm install vue-router@^4 vuex@^4

# 如果是 Vite 项目
npm install -D @vitejs/plugin-vue

步骤 2:配置别名(Vite)

javascript 复制代码
// vite.config.js
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [
    vue({
      template: {
        compilerOptions: {
          compatConfig: {
            MODE: 2  // 最大兼容模式
          }
        }
      }
    })
  ],
  resolve: {
    alias: {
      vue: '@vue/compat'  // 将 vue 指向迁移构建
    }
  }
})

步骤 3:配置 Webpack(Vue CLI)

javascript 复制代码
// vue.config.js
module.exports = {
  configureWebpack: {
    resolve: {
      alias: {
        vue: '@vue/compat'
      }
    }
  }
}

3.3 渐进式关闭兼容性

当项目在迁移构建下运行时,每个破坏性变更都会触发警告。你可以逐个修复 ,然后逐组件关闭兼容模式:

vue 复制代码
<script>
// 在组件级别关闭兼容模式
export default {
  compatConfig: {
    MODE: 3,  // Vue 3 模式,仅此组件
    // 或单独禁用某个特性
    COMPILER_V_IF: false
  }
}
</script>

全局配置:

javascript 复制代码
// main.js
import { configureCompat } from 'vue'

configureCompat({
  MODE: 2,  // 默认 Vue 2 模式
  // 逐步启用 Vue 3 特性
  COMPILER_V_IF: true,
  COMPILER_V_FOR: true
})

3.4 迁移构建的局限性

局限性 说明
依赖 Vue 2 内部 API 如 Vuetify、Quasar 等库依赖 Vue 2 内部实现,需等待 Vue 3 版本
IE11 支持 Vue 3 已放弃 IE11 支持
SSR 自定义 SSR 配置迁移较复杂
未文档化的行为 迁移构建仅覆盖公开 API

四、核心破坏性变更详解

4.1 全局 API 变更

① 不再使用 new Vue(),改用 createApp

javascript 复制代码
// ❌ Vue 2
import Vue from 'vue'
new Vue({
  render: h => h(App)
}).$mount('#app')

// ✅ Vue 3
import { createApp } from 'vue'
import App from './App.vue'
createApp(App).mount('#app')

② 全局配置迁移到 app 实例

javascript 复制代码
// ❌ Vue 2
Vue.config.productionTip = false
Vue.config.devtools = true
Vue.use(Plugin)
Vue.mixin(Mixin)
Vue.component('MyComponent', Component)

// ✅ Vue 3
const app = createApp(App)
app.config.productionTip = false
app.use(Plugin)
app.mixin(Mixin)
app.component('MyComponent', Component)

③ Vue.prototype → app.config.globalProperties

javascript 复制代码
// ❌ Vue 2
Vue.prototype.$http = axios

// ✅ Vue 3
app.config.globalProperties.$http = axios

④ Vue.set / Vue.delete 不再需要

Vue 3 的 Proxy 响应式系统原生支持动态新增属性和数组索引修改,不再需要 $set 和 $delete。

javascript 复制代码
// ❌ Vue 2
this.$set(this.obj, 'newProp', value)
this.$delete(this.obj, 'prop')

// ✅ Vue 3 - 直接赋值即可
this.obj.newProp = value
delete this.obj.prop

4.2 生命周期钩子改名

Vue 2 Vue 3
beforeDestroy beforeUnmount
destroyed unmounted
javascript 复制代码
// ❌ Vue 2
export default {
  beforeDestroy() { /* 清理 */ },
  destroyed() { /* 清理完成 */ }
}

// ✅ Vue 3 (选项式)
export default {
  beforeUnmount() { /* 清理 */ },
  unmounted() { /* 清理完成 */ }
}

// ✅ Vue 3 (组合式)
import { onBeforeUnmount, onUnmounted } from 'vue'
onBeforeUnmount(() => { /* 清理 */ })
onUnmounted(() => { /* 清理完成 */ })

4.3 v-model 变更

① 组件上的 v-model 默认 prop/event 改名

Vue 2 Vue 3
prop: value prop: modelValue
event: input event: update:modelValue
vue 复制代码
<!-- ❌ Vue 2 子组件 -->
<script>
export default {
  props: ['value'],
  methods: {
    update(val) { this.$emit('input', val) }
  }
}
</script>

<!-- ✅ Vue 3 子组件 -->
<script setup>
defineProps(['modelValue'])
const emit = defineEmits(['update:modelValue'])
</script>

② 支持多个 v-model 绑定

vue 复制代码
<!-- Vue 3 支持多个 v-model -->
<ChildComponent v-model:title="title" v-model:content="content" />

4.4 指令 API 变更

自定义指令的生命周期钩子与组件对齐:

Vue 2 Vue 3
bind beforeMount
inserted mounted
update beforeUpdate
componentUpdated updated
unbind unmounted
javascript 复制代码
// ❌ Vue 2
Vue.directive('focus', {
  inserted(el) { el.focus() }
})

// ✅ Vue 3
app.directive('focus', {
  mounted(el) { el.focus() }
})

4.5 事件总线移除

Vue 3 移除了 $on、$off、$once 实例方法,使用 mitt 替代:

javascript 复制代码
// ❌ Vue 2
const bus = new Vue()
bus.$on('event', handler)
bus.$emit('event', data)

// ✅ Vue 3 - 使用 mitt
import mitt from 'mitt'
const emitter = mitt()
emitter.on('event', handler)   // 监听
emitter.emit('event', data)    // 触发
emitter.off('event', handler)  // 移除

4.6 过滤器移除

Vue 3 移除了过滤器,使用计算属性 或方法替代:

vue 复制代码
<!-- ❌ Vue 2 -->
<template>
  <p>{{ price | currency }}</p>
</template>
<script>
export default {
  filters: {
    currency(val) { return '$' + val.toFixed(2) }
  }
}
</script>

<!-- ✅ Vue 3 - 计算属性 -->
<script setup>
import { computed } from 'vue'
const formattedPrice = computed(() => '$' + price.value.toFixed(2))
</script>
<template>
  <p>{{ formattedPrice }}</p>
</template>

4.7 其他重要变更

变更 Vue 2 Vue 3
$children 存在 已移除,使用 $refs
keyCode 修饰符 支持 已移除,使用按键名
propsData 支持 已移除
inline-template 支持 已移除
data 选项 可以是对象 必须是函数
<template> 多根 仅支持单根 支持多根节点
nextTick 多种实现 统一优化

五、生态工具升级

5.1 Vue Router 2 → 4

① 创建方式变更

javascript 复制代码
// ❌ Vue Router 3
import VueRouter from 'vue-router'
const router = new VueRouter({
  mode: 'history',
  routes: [...]
})

// ✅ Vue Router 4
import { createRouter, createWebHistory } from 'vue-router'
const router = createRouter({
  history: createWebHistory(),
  routes: [...]
})

② 导航守卫不再需要 next()

javascript 复制代码
// ❌ Vue Router 3
router.beforeEach((to, from, next) => {
  if (!isAuthenticated) {
    next('/login')
  } else {
    next()
  }
})

// ✅ Vue Router 4 - 直接返回值
router.beforeEach((to, from) => {
  if (!isAuthenticated) {
    return '/login'  // 重定向
  }
  // 返回 undefined 或 true 表示继续
})

③ router-link 变更

vue 复制代码
<!-- ❌ Vue 2 -->
<router-link :to="{ name: 'user', params: { id: 1 } }">用户</router-link>

<!-- ✅ Vue 3 - 使用 query 代替 params -->
<router-link :to="{ name: 'user', query: { id: 1 } }">用户</router-link>

5.2 Vuex 3 → 4 / Pinia

选项一:升级到 Vuex 4

javascript 复制代码
// ❌ Vuex 3
import Vuex from 'vuex'
const store = new Vuex.Store({
  state: { count: 0 },
  mutations: { increment(state) { state.count++ } }
})

// ✅ Vuex 4
import { createStore } from 'vuex'
const store = createStore({
  state: () => ({ count: 0 }),
  mutations: { increment(state) { state.count++ } }
})

选项二:迁移到 Pinia(官方推荐)

Pinia 是 Vue 官方的新一代状态管理库,API 更简洁、TypeScript 支持更好:

javascript 复制代码
// Vuex 3
const store = new Vuex.Store({
  state: { count: 0 },
  mutations: { increment(state) { state.count++ } },
  actions: { asyncIncrement({ commit }) { setTimeout(() => commit('increment'), 1000) } },
  getters: { doubleCount: state => state.count * 2 }
})

// Pinia
import { defineStore } from 'pinia'
export const useCounterStore = defineStore('counter', {
  state: () => ({ count: 0 }),
  actions: {
    increment() { this.count++ },
    async asyncIncrement() { await new Promise(r => setTimeout(r, 1000)); this.increment() }
  },
  getters: {
    doubleCount: (state) => state.count * 2
  }
})

5.3 UI 库升级

UI 库 Vue 2 版本 Vue 3 版本 迁移难度
Vuetify v2.x v3.x 高(API 大变)
Element UI Element UI Element Plus 中(API 基本兼容)
Ant Design Vue v1.x / v2.x v3.x / v4.x 中
Quasar v1.x v2.x 中

5.4 构建工具:Vue CLI → Vite

Vue 官方推荐使用 Vite 替代 Vue CLI:

bash 复制代码
# 创建新的 Vite + Vue 3 项目
npm create vite@latest my-project -- --template vue

# 或使用官方脚手架
npm create vue@latest

迁移要点:

  • vue.config.js → vite.config.js
  • 环境变量:process.env → import.meta.env
  • 静态资源:require() → import 或 new URL()

六、选项式 API 到组合式 API 的迁移

6.1 迁移策略

推荐方式:渐进式迁移,而非一次性重写

阶段 策略
阶段一 新组件使用组合式 API
阶段二 旧组件保持选项式 API
阶段三 重构复杂的旧组件到组合式 API
阶段四 逐步淘汰选项式 API

Vue 3 完全支持选项式 API,你不需要一次性迁移所有组件。

6.2 选项式 → 组合式 映射

选项式 API 组合式 API
data() ref() / reactive()
computed computed()
methods 普通函数
watch watch() / watchEffect()
mounted onMounted()
props defineProps()
emit defineEmits()

迁移示例:

vue 复制代码
<!-- ❌ Vue 2 选项式 -->
<script>
export default {
  props: ['userId'],
  data() {
    return { user: null, loading: false }
  },
  computed: {
    displayName() {
      return this.user?.name || '未知'
    }
  },
  methods: {
    async fetchUser() {
      this.loading = true
      this.user = await api.getUser(this.userId)
      this.loading = false
    }
  },
  watch: {
    userId: 'fetchUser'
  },
  mounted() {
    this.fetchUser()
  }
}
</script>

<!-- ✅ Vue 3 组合式 -->
<script setup>
import { ref, computed, watch, onMounted } from 'vue'

const props = defineProps(['userId'])

const user = ref(null)
const loading = ref(false)

const displayName = computed(() => user.value?.name || '未知')

async function fetchUser() {
  loading.value = true
  user.value = await api.getUser(props.userId)
  loading.value = false
}

watch(() => props.userId, fetchUser)
onMounted(fetchUser)
</script>

6.3 Mixins → 组合式函数

Vue 2 的 mixins 存在命名冲突和数据来源不清晰的问题,组合式函数是更好的替代方案:

javascript 复制代码
// ❌ Vue 2 - mixin
const userMixin = {
  data() {
    return { user: null }
  },
  methods: {
    fetchUser(id) { /* ... */ }
  }
}

// ✅ Vue 3 - 组合式函数
export function useUser() {
  const user = ref(null)
  async function fetchUser(id) {
    user.value = await api.getUser(id)
  }
  return { user, fetchUser }
}

七、常见问题与解决方案

7.1 依赖不兼容

问题:某些库没有 Vue 3 版本(如 Vuetify 2)

解决方案:

  1. 查找 Vue 3 替代库(Vuetify 2 → Vuetify 3)
  2. 暂时使用迁移构建(@vue/compat)
  3. 寻找功能相似的替代方案

7.2 全局注册的组件/指令

问题 :Vue 2 中通过 Vue.component() 全局注册的组件在 Vue 3 中不可用

解决方案 :迁移到 app.component() 或改为局部注册。

7.3 模板中的 {``{ }} 表达式变化

Vue 3 的模板表达式沙箱更严格,某些 Vue 2 中可用的全局变量可能不可用。

7.4 v-if 和 v-for 优先级变化

Vue 3 中 v-if 优先级高于 v-for(Vue 2 中相反),不要在同一元素上同时使用。

7.5 过渡类名变更

Vue 2 Vue 3
v-enter v-enter-from
v-leave v-leave-to

八、迁移检查清单

阶段一:升级到 Vue 2.7

  • 将 vue 升级到 ^2.7.0
  • 升级 @vue/cli-xxx 到最新版本
  • 安装 @vue/composition-api(如果使用)
  • 验证项目在 Vue 2.7 下正常运行
  • 新模块开始使用 Composition API

阶段二:迁移构建

  • 安装 vue@^3 和 @vue/compat
  • 配置构建工具别名指向 @vue/compat
  • 升级 vue-router 到 v4
  • 升级 vuex 到 v4 或迁移到 Pinia
  • 升级 UI 库到 Vue 3 版本
  • 运行项目,查看控制台警告
  • 逐个修复警告

阶段三:切换到标准 Vue 3

  • 所有兼容性警告已修复
  • 移除 @vue/compat 别名
  • 将 vue 指向标准版本
  • 验证所有功能正常
  • 运行生产构建测试

阶段四:组合式 API 迁移(可选)

  • 新组件使用 <script setup>
  • 将 mixins 重构为组合式函数
  • 逐步重构复杂组件
  • 统一代码风格

九、迁移工具推荐

工具 用途 说明
@vue/compat 兼容性运行 Vue 3 官方迁移构建
vue3-breaking-changes-scanner 代码扫描 扫描 Vue 2 特有 API
GoGoCode AST 转换 自动化代码转换
vue-ai-migrator AI 辅助迁移 AST + AI 智能转换
ESLint 规则 代码检查 防止使用已弃用功能

十、本篇小结

知识点 核心内容
迁移策略 渐进式迁移:2.7 → @vue/compat → 标准 Vue 3
迁移构建 @vue/compat 提供 Vue 2 兼容模式
全局 API new Vue() → createApp()
生命周期 beforeDestroy → beforeUnmount,destroyed → unmounted
v-model value → modelValue,input → update:modelValue
指令 API 钩子名称与组件生命周期对齐
事件总线 使用 mitt 替代
过滤器 使用计算属性或方法替代
Vue Router v3 → v4,导航守卫不再需要 next()
Vuex v3 → v4 或迁移到 Pinia
组合式 API 渐进式引入,新旧共存

十一、思考与练习

  1. 评估练习:检查你当前的项目(或一个示例项目),列出所有需要升级的依赖及其 Vue 3 兼容版本。

  2. 实践任务:在一个小型 Vue 2 项目中,按"2.7 → @vue/compat → 标准 Vue 3"的路径完成迁移,记录每一步遇到的问题和解决方案。

  3. 代码转换:将一个 Vue 2 组件(包含 data、computed、methods、watch、mounted)手动转换为 Vue 3 组合式 API 写法。

  4. 深度思考:为什么 Vue 团队推荐渐进式迁移而非一次性重写?在什么情况下"大爆炸"式重写可能是更好的选择?

  5. 扩展任务 :研究 vue-ai-migrator 或 GoGoCode 等自动化迁移工具,在一个测试项目上运行,分析自动转换的准确率和需要手动修正的部分。

下篇预告

第 19 篇我们将开启生态工具篇 ,学习 Vite------新一代前端构建工具:

  • Vite 的 No-Bundle 理念与原理
  • 依赖预构建(esbuild)
  • HMR 热更新机制
  • Vite 配置详解
  • 与 Webpack 的全面对比

准备好拥抱更快的构建体验!⚡

相关推荐
保利威视频SaaS小张1 小时前
企业直播接入笔记 12|企业内训直播怎么做签到和学时统计,防挂机这件事比想象中难
java·前端·数据库·笔记·视频云·polvy·polyv
bysking1 小时前
GitHub Actions 快速入门+场景实践案例
前端·后端·github
广州华水科技2 小时前
单北斗GNSS变形监测系统在大坝安全维护中的重要性
前端
anyup2 小时前
自带 uni-app x 页面级能力,uView Pro X 8 个开箱即用的工具函数
前端·vue.js·uni-app
涛涛ing2 小时前
别拿 Chrome 跑通了就提测:把这段 AI 写的代码发到 Safari 上,我差点丢了工作
前端
墨林陌2 小时前
用 AI 给娃做了一个识物游戏:一份 2.3MB 的单文件 HTML,126 张卡片、三种玩法,手机平板打开就能玩
前端
Hilaku2 小时前
Claude Code 过夜跑长任务实战:tmux、权限、验收,以及我为什么换到 ApexOne
前端·javascript·程序员
程序员大阳2 小时前
副队长ES6+教程(14)--手写Promise来加深理解
前端·javascript·es6·源码·promise·手写·深层
J船长2 小时前
从 Trellis 看 AI 研发工具选型:OpenSpec、Spec Kit 与 Harness 如何配合
前端