本篇定位: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)
解决方案:
- 查找 Vue 3 替代库(Vuetify 2 → Vuetify 3)
- 暂时使用迁移构建(
@vue/compat) - 寻找功能相似的替代方案
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 | 渐进式引入,新旧共存 |
十一、思考与练习
-
评估练习:检查你当前的项目(或一个示例项目),列出所有需要升级的依赖及其 Vue 3 兼容版本。
-
实践任务:在一个小型 Vue 2 项目中,按"2.7 → @vue/compat → 标准 Vue 3"的路径完成迁移,记录每一步遇到的问题和解决方案。
-
代码转换:将一个 Vue 2 组件(包含 data、computed、methods、watch、mounted)手动转换为 Vue 3 组合式 API 写法。
-
深度思考:为什么 Vue 团队推荐渐进式迁移而非一次性重写?在什么情况下"大爆炸"式重写可能是更好的选择?
-
扩展任务 :研究
vue-ai-migrator或GoGoCode等自动化迁移工具,在一个测试项目上运行,分析自动转换的准确率和需要手动修正的部分。
下篇预告
第 19 篇我们将开启生态工具篇 ,学习 Vite------新一代前端构建工具:
- Vite 的 No-Bundle 理念与原理
- 依赖预构建(esbuild)
- HMR 热更新机制
- Vite 配置详解
- 与 Webpack 的全面对比
准备好拥抱更快的构建体验!⚡