Vue 2 项目迁移到 Vue 3 的完整注意事项和迁移策略

一、迁移前准备

1. 评估必要性

• 确认项目是否需要 Vue 3 的新特性（性能优化、组合式 API、TS 支持等）

• 检查依赖库的 Vue 3 支持情况（Element UI → Element Plus，Vuex → Pinia 等）

版本升级路径

bashVue 2.6 → 2.7（支持 Composition API） → Vue 3.0

使用迁移工具

• 官方迁移构建工具 @vue/compat

  bashnpm install vue@3.1.4 @vue/compat@3.1.4

二、破坏性变更处理（优先级最高）

1. 全局 API 变更

• 修改点：

  javascript// Vue 2import Vue from 'vue'Vue.component('comp', Comp)// Vue 3import { createApp } from 'vue'const app = createApp(App)app.component('comp', Comp)

• 解决方案：
  使用 app.config.globalProperties 替代 Vue.prototype

2. 事件总线模式弃用

• 修改点：

  javascript// Vue 2const bus = new Vue()bus.$on(...)bus.$emit(...)// Vue 3 替代方案import mitt from 'mitt'const emitter = mitt()

3. 过滤器（Filter）移除

• 修改点：

  vue<!-- Vue 2 -->{{ price | currency }}
  
  <!-- Vue 3 替代方案 -->
  {{ formatCurrency(price) }}

• 解决方案：
  改用计算属性或全局方法

三、模板语法调整

1. 多根节点支持（Fragment）

vue<!-- Vue 2 需要单根元素 --><template>
  <div>
    <header></header>
    <main></main>
  </div>
</template>

<!-- Vue 3 允许多根 -->
<template>
  <header></header>
  <main></main>
</template>

2. v-model 变更

• 修改点：

  vue<!-- Vue 2 --><ChildComponent v-model="value" />
  
  <!-- Vue 3 等价写法 -->
  <ChildComponent :modelValue="value" @update:modelValue="value = $event" />

• 多 v-model 支持：

  vue<UserForm 
    v-model:name="userName"
    v-model:age="userAge"
  />

四、响应式系统重构

1. 数组响应式更新

• 修改点：

  javascript// Vue 2 需要 Vue.setVue.set(this.items, index, newValue)// Vue 3 直接操作this.items[index] = newValue

2. 响应式 API 变更

javascript// Vue 2this.$set(this.obj, 'key', value)// Vue 3import { set } from 'vue'set(obj, 'key', value)

五、生命周期调整

六、生态系统迁移

1. 路由升级（Vue Router 3 → 4）

javascript// Vue 2new VueRouter({ mode: 'history' })// Vue 3import { createRouter, createWebHistory } from 'vue-router'createRouter({  history: createWebHistory(),  routes})

2. 状态管理（Vuex → Pinia）

javascript// Vuex 3 → Pinia// store/modules/user.js → stores/user.jsexport const useUserStore = defineStore('user', {  state: () => ({ name: '' }),  actions: {    async fetchUser() { /* ... */ }  }})

七、组合式 API 重构策略

1. 渐进式迁移步骤

1. 在 Vue 2.7 中测试组合式 API

2. 使用 <script setup> 语法重构组件

3. 抽离可复用的 Composition 函数

2. 选项式 → 组合式示例

javascript// Vue 2 选项式export default {  data() {    return { count: 0 }  },  methods: {    increment() {      this.count++    }  }}// Vue 3 组合式<script setup>import { ref } from 'vue'const count = ref(0)const increment = () => count.value++</script>

八、TypeScript 增强

1. Props 类型定义

   typescriptinterface Props {  title: string  size?: 'small' | 'medium'}const props = defineProps<Props>()

2. 自定义事件类型

   typescriptconst emit = defineEmits<{  (e: 'update', value: number): void  (e: 'submit'): void}>()

九、测试与验证

1. 单元测试更新

   javascript// Vue 2import { shallowMount } from '@vue/test-utils'// Vue 3import { mount } from '@vue/test-utils-vue3'

2. 兼容性检查清单：

• IE11 支持需额外配置（@vue/compat + polyfill）

• 第三方库兼容性验证（Vue-i18n → v9+，Vuetify → v3+）

十、迁移后优化

1. Tree-shaking 收益
   删除 Vue.config.ignoredElements 等无用配置

2. 性能提升验证
   使用 Chrome DevTools 的 Performance 面板对比组件渲染时间

总结：迁移路径图

mermaidgraph TD    A[评估必要性] --> B[升级到 Vue 2.7]    B --> C[使用 @vue/compat 模式]    C --> D[处理破坏性变更]    D --> E[迁移 Vue Router/Vuex]    E --> F[重构组合式 API]    F --> G[移除兼容模式]    G --> H[优化新特性]

通过分阶段、渐进式的迁移策略，可以最大限度降低升级风险。建议优先在非核心模块试点，验证稳定后再全量迁移。