Vue2 升级 Vue3 一文通关沉默是金，总会发光大家好，我是沉默最近公司在搞前端技术升级，想让我把老项目从 Vu

沉默是金，总会发光

大家好，我是沉默

最近公司在搞前端技术升级，想让我把老项目从 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

| 依赖库

| | --- | --- | --- | |

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 框架和插件兼容性

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 vuexnpm install vue@3.2.47 vue-router@4 vuex@4npm 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.jsimport { 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. 全局属性注册方式变了

// Vue2Vue.prototype.$http = axios// Vue3app.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.jsimport 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-uinpm 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 写法，建议定期进行代码审查和重构。

Vue2 升级 Vue3 一文通关