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 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.jsimport { 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-

成功升级后注意什么？

1. 团队习惯切换：Composition API 是 Vue3 的核心，需要团队成员逐步适应其写法和逻辑拆分方式。

2. 依赖更新策略：持续关注第三方库的更新，避免再次陷入版本孤岛。

3. 编码规范同步：建议制定统一的 Vue3 编码规范，例如组件命名、setup() 写法风格、状态管理组织方式等。

4. 定期技术债检查：升级后仍可能残留一些 Vue2 写法，建议定期进行代码审查和重构。

推荐阅读

• Vue3 迁移指南

-04-

粉丝福利

点点关注，送你 Spring Boot Vue 全栈开发实战，如果你正在做项目，又或者刚准备做。可以仔细阅读一下，或许对你有所帮助！