Vue2 升级 Vue3 要注意啥？从语法到生态一篇讲透

<template>
  <ElIcon><Search /></ElIcon>
</template>
<script setup>
import { ElIcon, Search } from '@element-plus/icons-vue'
</script>

样式引入也有暗坑：Vue2里引入Element UI样式是import 'element-ui/lib/theme-chalk/index.css'，Vue3的Element Plus得改成import 'element-plus/dist/index.css'，要是路径写错，整个组件库样式会“失踪”，按钮变成白板。

还有组件逻辑调整，比如Tree组件的懒加载，Vue2里用lazy属性+load方法，Vue3里得配合useLazyLoad钩子，参数传递方式完全不同，必须对照官方迁移文档一行行改。

路由和状态管理：Vue Router、Vuex 咋升级？

Vue Router从3.x跳到4.x，最直观的是创建路由的方式：

• Vue2写法：

  import Vue from 'vue'
  import VueRouter from 'vue-router'
  Vue.use(VueRouter)
  const router = new VueRouter({
    routes: [/* 路由配置 */]
  })
  export default router

• Vue3写法：

  import { createRouter, createWebHistory } from 'vue-router'
  const router = createRouter({
    history: createWebHistory(), // 替代原来的mode: 'history'
    routes: [/* 路由配置 */]
  })
  export default router

路由跳转的语法，虽然this.$router.push('/home')还能临时用，但Vue3推荐用useRouter hooks：

import { useRouter } from 'vue-router'
const router = useRouter()
router.push('/home')

Vuex的升级相对温和，Vuex 4.x对Vue3做了兼容，但社区更推荐Pinia（由Vuex核心团队开发），Pinia完全抛弃了Vuex的modules、mutations这些“繁文缛节”，用更简洁的函数式写法：

• Vuex定义模块：

  const userModule = {
    state: () => ({ name: '' }),
    mutations: { setName(state, name) { state.name = name } }
  }

• Pinia定义store：

  import { defineStore } from 'pinia'
  export const useUserStore = defineStore('user', {
    state: () => ({ name: '' }),
    actions: { setName(name) { this.name = name } } // 没有mutations，直接在actions里改状态
  })

  Pinia天生支持Composition API，在组件里用const userStore = useUserStore()就能拿到响应式状态，比Vuex的mapState、mapActions清爽太多。

构建工具：Vue CLI 转 Vite 能提速多少？

Vue2项目用Vue CLI（基于Webpack）启动时，得等Webpack把所有依赖打包，冷启动可能要几十秒；换成Vite后，利用ESModule的特性，冷启动秒级完成，开发时修改代码也是“秒更”，但迁移不是“一键替换”，得处理这些差异：

• 配置文件：Vue CLI用vue.config.js，Vite用vite.config.js，比如配置别名，Vue CLI里是：

  chainWebpack: config => { 
    config.resolve.alias.set('@', path.resolve(__dirname, 'src')) 
  }

  Vite里直接写：

  resolve: { 
    alias: { '@': path.resolve(__dirname, 'src') } 
  }

• 依赖兼容：Vite默认只认ESModule格式的包，有些老库是CommonJS写的（比如某些日期处理库），得装vite-plugin-commonjs插件转换，要是项目里用了require('xxx')语法，也得改成import。

• 环境变量：Vue CLI里的process.env.VUE_APP_XXX，Vite里要改成import.meta.env.VITEXXX，还要在.env文件里把前缀改成VITE。

如果团队暂时不想换构建工具，Vue CLI也能支持Vue3——把@vue/cli-service升级到5.x版本，vue-loader升到16+，再把项目里的Vue版本改成3.x，就能在Webpack环境下跑Vue3代码。

实战升级步骤，怎么降低风险？

升级是个“技术活”，得用“小步快跑、逐步验证”的策略，别搞“大爆炸式重构”。

先拿“小模块”练手

别直接动核心页面，先挑独立的小组件，比如弹窗、按钮组件，比如把项目里的Confirm组件用Vue3重写，用setup语法糖，把原来的data、methods改成ref、function，测试响应式和事件逻辑是否正常，跑通一个组件后，再逐步替换列表、表单这些复杂组件。

举个🌰：重构Button组件
原来Vue2的Button组件可能长这样：

export default {
  props: { type: String },
  data() { return { loading: false } },
  methods: {
    handleClick() { this.$emit('click') }
  }
}

Vue3重写后（用语法糖）：

<script setup>
const props = defineProps({ type: String })
const emit = defineEmits(['click'])
const loading = ref(false)
const handleClick = () => emit('click')
</script>

改完后，在测试页面里反复点击、传参，确认功能和样式都没崩，再推进下一个组件。

依赖版本锁死，避免“版本乱战”

升级时package.json里的依赖要逐个检查：vue升级到3.x，vue-loader要16+，vue-router4.x，vuex4.x（或Pinia），升级后先npm install，看有没有依赖冲突，用npm ls查依赖树。

比如曾经有项目升级时，eslint-plugin-vue版本没同步，导致代码检查报错，后来把eslint-plugin-vue升到9.x才解决，所以升级后一定要锁定依赖版本，避免不同依赖之间“打架”。

测试环节必须“武装到牙齿”

升级后功能有没有崩？样式有没有乱？得靠测试把把关：

• 单元测试：用Vue Test Utils 2.x，原来的mount、shallowMount用法有变化，比如现在要导入from '@vue/test-utils'，比如测试Button组件的点击事件：

  import { mount } from '@vue/test-utils'
  import MyButton from './MyButton.vue'
  test('button click emits event', () => {
    const wrapper = mount(MyButton)
    wrapper.trigger('click')
    expect(wrapper.emitted('click')).toBeTruthy()
  })

• E2E测试：用Cypress或Playwright，把核心流程（比如登录、下单）跑一遍，确保升级后功能没断，还可以加可视化diff工具（比如Argos），对比升级前后页面渲染是否一致，防止样式崩掉。

性能监控：升级后真的变快了吗？

Vue3的Tree-shaking能把没用的代码删掉，包体积通常能减小30%以上，用webpack-bundle-analyzer（Vue CLI项目）或vite-plugin-bundle-visualizer（Vite项目）看打包后的chunk大小，对比升级前后。

运行时性能方面，用Chrome DevTools的Performance面板，记录组件渲染时间，Vue3的响应式追踪更高效，复杂列表的渲染速度应该有提升，要是发现某些组件反而变慢，可能是reactive用多了（reactive对对象深度监听，性能开销比ref大），换成ref更轻量。

这些“大坑”升级时千万避开！

升级路上总有意外，这几个高频“暗礁”得提前防住。

第三方库突然“不认识”Vue3了

有些老库只支持Vue2，比如某些图表库、地图SDK，这时候要么找替代库（比如ECharts有官方Vue3组件），要么自己封装适配层：把Vue3的组件用defineComponent