Vue2 升级 Vue3 一文通关
沉默是金，总会发光
大家好，我是沉默
最近公司在搞前端技术升级，想让我把老项目从 Vue2 升级到 Vue3，我在网上翻了不少文章，发现几乎没有一篇能系统、完整地把升级流程讲清楚的，于是我干脆自己动手，边升级边总结，写了这篇文章：为啥要升级 Vue3，如何升级到 Vue3，以及升级后需要注意什么？如果你也正好在搞 Vue 升级，那这篇文章应该能帮上你。
-01-
为什么要升级 Vue3?
我们可以在官网看到，Vue2 已经停止更新了，避免面临生态支持逐渐减少的风险，并且 Vue3 带来的性能优化、语法升级和更现代的开发体验。升级到 Vue3 是势在必行的选择！
Vue3 带来了很多实打实的好处：
1. 性能更强
- Vue3 使用了全新的 Proxy 响应式系统（取代 Vue2 的 Object.defineProperty），响应式性能更好，追踪依赖更精准。
2. 更好的 TypeScript 支持
- Vue3 原生支持 TypeScript，类型推导更准确，提升开发效率和代码质量。
3. 组合式 API 更灵活
- 通过 setup() 和 Composition API，逻辑复用更加清晰，有助于大型项目的可维护性和模块化。
4. 更好的生态未来
- Vue 官方生态（Vue Router、Vuex、Pinia、Vite 等）已经全面适配 Vue3。
- 新组件库（如 Element Plus、Naive UI、Ant Design Vue 2.x）也都基于 Vue3 开发。
当然，升级的过程并不算轻松，尤其是对于体量较大或依赖较多的项目来说，更是充满挑战。为了帮助大家少踩坑、少走弯路，接下来将从前期准备、实际操作到最终验证与优化，梳理出一套清晰可行的升级思路，带你一步步完成 Vue2 向 Vue3 的平稳迁移。
-02-
我们如何升级到 Vue3？
第一阶段：升级前的准备工作
1. 理清项目的依赖现状
升级前，建议先确认当前使用的 Vue 生态版本：
npm list vue vue-router vuex然后参考下方表格对照 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 |
vue-loader | vue-loader@15.x | vue-loader@16.x + |
2. 检查 UI 框架和插件兼容性
推荐命令快速查找所有依赖中的 vue 插件：
npm list | grep 'vue'大多数 Vue2 生态中的插件/库在 Vue3 下都有更新版本或替代方案。以下是常见的替换建议：
类型 | Vue2 常用 | Vue3 替代 |
UI 框架 | Element UI | Element Plus |
i18n | vue-i18n@8 | vue-i18n@9 |
本地持久化 | vuex-persisted | vuex-persistedstate@4 |
表单验证 | vee-validate@2/3 | vee-validate@4 |
3. 创建一个干净的迁移分支
避免直接在主分支操作：
git checkout -b vue3-migration
同时备份关键配置文件：package.json
, vue.config.js
, babel.config.js 等。4. 语法兼容性检查
Vue3 移除了一些 Vue2 的语法特性，要提前做好准备：
Vue2 语法 | Vue3 替代方案 |
过滤器 (Filters) | 用全局方法或组件内部逻辑替代 |
事件总线 (Event Bus) | 用 mitt 或其他事件库替代 |
$on, $off, $once | 使用 mitt 或其他事件库 |
第二阶段：替换依赖 + 初始化 Vue3 应用
1. 替换核心依赖
npm remove vue vue-router vuex
npm install vue@3.2.47 vue-router@4 vuex@4
npm install @vue/compiler-sfc@3.2.47 -D
2. 重写入口文件 main.js
Vue3 使用 createApp() 替代了 Vue 实例化方式。
// Vue3 main.js
import { createApp } from 'vue'
import App from './App.vue'
const app = createApp(App)
app.mount('#app')3. 注册路由和 Vuex 新方式
// router/index.js
import { createRouter, createWebHistory } from 'vue-router'
const router = createRouter({
history: createWebHistory(), routes })
// store/index.js
import { createStore } from 'vuex'
const store = createStore({
state: {}, mutations: {}, actions: {} })
// main.js
app.use(router)
app.use(store)
第三阶段：语法兼容性重构
1. 全局属性注册方式变了
// Vue2
Vue.prototype.$http = axios
// Vue3
app.config.globalProperties.$http = axios
2. 过滤器不再支持，改用方法或计算属性
// 定义全局方法
app.config.globalProperties.$filters = {
capitalize(value) {
return value.charAt(0).toUpperCase() + value.slice(1)
}}
// 模板中调用
{{ $filters.capitalize(message) }}
3. 替换事件总线：推荐 mitt
npm install mitt
// event-bus.js
import mitt from 'mitt'
export const emitter = mitt()
// 使用方式
emitter.emit('custom-event')
emitter.on('custom-event', callback)
4.从 Options API 到 Composition API// Vue 2 写法
export default {
data() {
return {
count: 0
}
},
methods: {
increment() {
this.count++
}
}
}
// Vue 3 写法
import { ref } from 'vue'
export default {
setup() {
const count = ref(0)
const increment = () => count.value++
return { count, increment }
}
}
第四阶段：UI 组件库替换（以 Element UI 为例）
npm remove element-ui
npm install element-plus @element-plus/icons-vue
注册方式：
import ElementPlus from 'element-plus'
import 'element-plus/dist/index.css'
app.use(ElementPlus)
第五阶段：调试 & 验证兼容性
1. 常见迁移报错排查
- 找不到 Vue 默认导出：检查 import Vue from 'vue' 是否仍存在
- use 报错：确保使用了 Vue3 的 createApp() 实例
2. 建议的验证策略
- 起步时仅保留一个基础页面；
- 分模块解耦测试；
- 使用 Vue Devtools 6+ 检查组件行为；
- 若组件库不兼容，可暂时使用 Vue3 的兼容构建版本。
3. 启用 Vue2 兼容模式（可选）
import { configureCompat } from 'vue'
configureCompat({ MODE: 2 // 启用 Vue2 部分 API})提示：需搭配安装 vue@3.1.0-compat。
第六阶段：官方工具推荐
1. 自动兼容分析工具
npx @vue/compat
2. Vue3 测试工具
npm install @vue/test-utils@next -D
最后一步：清理与优化
1. 清除旧语法 & 兼容构建依赖；
2. 移除无用的 Vue2 特性，如 $on, filters；
3. 若使用 TypeScript，更新 @vue/runtime-core 类型定义；
4. 对所有组件进行单元测试验证；
-03-
成功升级后注意什么？
- 团队习惯切换：Composition API 是 Vue3 的核心，需要团队成员逐步适应其写法和逻辑拆分方式。
- 依赖更新策略：持续关注第三方库的更新，避免再次陷入版本孤岛。
- 编码规范同步：建议制定统一的 Vue3 编码规范，例如组件命名、setup() 写法风格、状态管理组织方式等。
- 定期技术债检查：升级后仍可能残留一些 Vue2 写法，建议定期进行代码审查和重构。
推荐阅读
- Vue3 迁移指南
-04-
粉丝福利
关注
：架构师沉默，送你 Spring Boot Vue 全栈开发实战，如果你正在做项目，又或者刚准备做。可以仔细阅读一下，或许对你有所帮助！