沉默是金，总会发光

大家好，我是沉默

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

2. 检查 UI 框架和插件兼容性

推荐命令快速查找所有依赖中的 vue 插件：

npm list | grep 'vue'

大多数 Vue2 生态中的插件/库在 Vue3 下都有更新版本或替代方案。以下是常见的替换建议：

3. 创建一个干净的迁移分支

避免直接在主分支操作：

git checkout -b vue3-migration
同时备份关键配置文件：package.json
, vue.config.js
, babel.config.js 等。

4. 语法兼容性检查

Vue3 移除了一些 Vue2 的语法特性，要提前做好准备：

第二阶段：替换依赖 + 初始化 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-

成功升级后注意什么？

1. 团队习惯切换：Composition API 是 Vue3 的核心，需要团队成员逐步适应其写法和逻辑拆分方式。
2. 依赖更新策略：持续关注第三方库的更新，避免再次陷入版本孤岛。
3. 编码规范同步：建议制定统一的 Vue3 编码规范，例如组件命名、setup() 写法风格、状态管理组织方式等。
4. 定期技术债检查：升级后仍可能残留一些 Vue2 写法，建议定期进行代码审查和重构。

推荐阅读

• Vue3 迁移指南

-04-

粉丝福利

关注

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