Vue2 到 Vue3 的终极升级指南：手把手教你顺利完成迁移！

小编正在做一个全栈的学习项目，因为最初跟着黑马的课学vue框架，所以不小心上了vue2的贼船，初期整个项目的前端架构是 vue2 ，但是众所周知：

引言：为什么升级到 Vue3？

Vue.js 是前端开发领域最受欢迎的框架之一，而 Vue3 的发布无疑为开发者带来了全新的体验和性能提升。如果你还在使用 Vue2，那么升级到 Vue3 是一个势在必行的选择！

Vue3 带来了以下显著优势：

• 性能提升：更快的渲染速度和更低的内存占用。
• 新特性：Composition API、Teleport、Suspense 等强大功能。
• 生态系统升级：Vue Router、Vuex 等核心库全面优化。

然而，升级过程并非 trivial（简单的），尤其是对于大型项目来说，可能会遇到诸多挑战。本文将为你提供一份详尽的升级指南，从前期准备到实际操作，再到验证与优化，手把手带你完成 Vue2 到 Vue3 的迁移！

所以我们该如何升级到vue3呢？

本篇文章是基于DeepSeek给出的步骤做了全面的补充，小编自己也是从头到尾跑通了一遍！

一、升级前的准备工作：未雨绸缪

1. 核心依赖检查

在开始升级之前，你需要明确当前项目的依赖版本，并确保它们与 Vue3 兼容。以下是典型的 Vue2 项目依赖及其对应的 Vue3 版本：

依赖	Vue2 版本	Vue3 版本
Vue	vue@2.6.x	vue@3.2.x
Vue Router	vue-router@3.x	vue-router@4.x
Vuex	vuex@3.x	vuex@4.x

检查命令：

npm list vue vue-router vuex

2. UI 组件库检查

如果你使用了第三方 UI 组件库，也需要确保它们支持 Vue3。以下是一些常见组件库的迁移方案：

组件库	迁移方案
Element UI	替换为 Element Plus
Vuetify	升级到 v3+版本
Ant Design Vue	升级到 v3+版本

3. 第三方插件检查

某些第三方插件可能不兼容 Vue3，因此需要提前检查并升级：

插件	迁移方案
vue-i18n	升级到 v9+
vuex-persistedstate	升级到 v4+
vue-loader	升级到 v16+

检查命令：

npm list | grep 'vue'

4. 语法兼容性检查

Vue3 移除了部分 Vue2 的语法特性，你需要提前做好准备：

Vue2 语法	Vue3 替代方案
过滤器（Filters）	使用全局方法或组件内逻辑
事件总线（Event Bus）	替换为 mitt 或其他事件管理库
$on, $off, $once	使用 mitt 或其他事件管理库

---

二、创建安全的升级环境

1. 创建新分支

为了防止升级过程中出现问题影响主分支，建议创建一个专门用于迁移的新分支：

git checkout -b vue3-migration

2. 备份重要文件

在开始升级之前，备份以下重要文件：

• package.json
• vue.config.js
• babel.config.js
• 所有 .vue 文件（通过 Git 自动备份）

---

三、逐步升级操作

1. 升级核心依赖

# 卸载旧版本 
npm remove vue vue-router vuex 

# 安装 Vue3 核心依赖 
npm install vue@3.2.47 vue-router@4 vuex@4 

# 更新编译器 
npm install @vue/compiler-sfc@3.2.47 -D

2. 修改 main.js

Vue3 引入了新的 API，你需要将 Vue2 的写法修改为 Vue3 的写法：

Vue2 写法：

import Vue from 'vue' 
import App from './App.vue' 
new Vue({ render: h => h(App), }).$mount('#app')

Vue3 写法：

import { createApp } from 'vue' 
import App from './App.vue' 
const app = createApp(App) app.mount('#app')

3. 处理 Vue Router

Vue Router 在 Vue3 中也进行了重大更新，以下是修改示例：

router/index.js 修改示例：

import { createRouter, createWebHistory } from 'vue-router' 
const router = createRouter({ 
    history: createWebHistory(), 
    routes // 保持原有路由配置 
})

main.js 中的修改：

app.use(router)

4. 处理 Vuex

Vuex 在 Vue3 中同样进行了优化，以下是修改示例：

store/index.js 修改示例：

import { createStore } from 'vuex' 
export default createStore({ 
    state: {}, 
    mutations: {}, 
    actions: {} 
})

main.js 中的修改：

app.use(store)

---

四、处理破坏性变更

1. 全局 API 修改

Vue3 移除了部分全局 API，你需要将其迁移到组件实例中：

Vue2 写法：

Vue.prototype.$http = axios

Vue3 写法：

app.config.globalProperties.$http = axios

2. 事件总线替代方案

Vue3 不再支持事件总线，你可以使用 mitt 库作为替代方案：

安装 mitt：

npm install mitt

使用示例：

// event-bus.js import mitt from 'mitt' export const emitter = mitt() 
// 发送事件 emitter.emit('event') 
// 监听事件 emitter.on('event', callback)

3. 过滤器迁移方案

Vue3 移除了过滤器功能，你需要将其迁移到全局方法中：

Vue2 写法：

{{ message | capitalize }}

Vue3 写法：

// 在 main.js 中定义全局方法 
app.config.globalProperties.$filters = { capitalize(value) { /* ... */ } } 
// 在模板中使用 {{ $filters.capitalize(message) }}

---

五、处理 UI 组件库（以 Element UI 为例）

1. 卸载旧版本

npm remove element-ui

2. 安装 Element Plus

npm install element-plus @element-plus/icons-vue

3. 修改引入方式

import ElementPlus from 'element-plus' 
import 'element-plus/dist/index.css' 
import { ElButton } from 'element-plus' 
// 按需引入需要额外配置 app.use(ElementPlus)

---

六、验证与调试

1. 启动时常见错误处理

• "export 'default' (imported as 'Vue') was not found"：检查是否还有 import Vue from 'vue' 残留。
• "Cannot read property 'use' of undefined"：确认 Vue Router 和 Vuex 是否使用新版创建方式。

2. 逐步验证策略

• 先注释所有路由和组件注册。
• 逐步放开核心页面。
• 使用 Chrome Vue Devtools 6.x+ 验证组件树。

3. 启用兼容模式（最后手段）

import { configureCompat } from 'vue' 
configureCompat({ 
    MODE: 2 // 启用部分 Vue2 兼容模式 
})

---

七、迁移工具推荐

1. 使用官方迁移构建版本

npm install vue@3.1.0-compat

2. 运行迁移检查工具

npx @vue/compat@latest

---

八、最终清理

1. 移除兼容模式配置

• 清理所有 @vue/compat 相关代码。

2. 更新测试用例

npm install @vue/test-utils@next -D

---

关键注意事项

1. 不要试图一次性完成所有修改，建议按功能模块逐步迁移。
2. 特别注意第三方库的 CDN 引入方式需要更新。
3. 如果使用 TypeScript，需要更新 @vue/runtime-core 类型定义。
4. v-model 的 prop/event 默认名称已从 value/input 改为 modelValue/update:modelValue。
5. 建议在升级过程中持续参考 Vue3 官方迁移指南，遇到具体问题可以结合错误信息查询对应变更说明。

---

结语：成功迁移后的下一步

完成 Vue2 到 Vue3 的迁移后，你的项目将获得更好的性能和更多的新特性。接下来，你可以进一步优化代码结构，探索 Vue3 的新功能，并为未来的开发打下坚实的基础！

如果你在迁移过程中遇到了任何问题，欢迎在评论区留言，我会尽力为你解答！

---

推荐阅读

• Vue3 官方文档
• Vue3 迁移指南
• Element Plus 官方文档