Vue3 + Vite 迁移记录：比预想中顺利

团队一个 Vue2 + webpack4 的中后台项目，构建已经要 3 分多钟，热更新也要 10 秒起步。趁着版本间隙，花了两周迁到 Vue3 + Vite。记录一下迁移路线和坑，给大家参考。

迁移前的评估

先跑了一遍官方的 gogocode/vue-codemod 之类的迁移工具，看依赖兼容性。结论：核心依赖（vuex、vue-router、ElementUI）都有对应升级路径，最麻烦的是那些停在 Vue2 时代的内部组件库。评估后决定：业务组件迁 Composition API，内部组件库里没人维护的部分借机用 Element Plus 重写（本来也烂）。

实际迁移过程

构建工具先行。先在 Vue2 下把 webpack 换成 Vite（用 vite-plugin-vue2），构建从 3 分钟降到 20 秒，团队立刻有了继续迁的动力。工具链先行的另一个好处是后面临时回退也不影响构建。

然后 Vue3。大头几类：filters 全删（V3 移除了，改成 computed 或方法）；EventBus 换 mitt；v-model 的 prop/event 命名改 sync 语法；ElementUI 换 Element Plus，表单校验 API 有变化，靠全局搜索一个一个过。代码量 5 万行的项目，配合迁移工具，净工作量大概 5 个人日。

踩的坑

• 依赖预构建缓存坑：某个 CJS 依赖在 dev 环境正常、build 后报错，原因是 optimizeDeps 没把它预构建。加进 optimizeDeps.include 解决。遇到"dev 好 build 挂"优先怀疑这里
• 环境变量：process.env.VUE_APP_x 全换成 import.meta.env.VITE_x，写了个脚本全局替换，注意别把 node 端的 process.env（vite.config 里）也换了
• 代理配置：devServer.proxy 换成 server.proxy，changeOrigin 默认值行为有差异，跨域 404 了一阵才定位到
• Composition API 不是重写理由：options API 在 Vue3 里完全合法。我们只在新代码和顺手改的组件里用 setup 语法糖，没有为了"风格统一"去全量重写——那种重构零收益且高风险

结果

构建 3min → 18s，热更新 10s → 300ms 内，打包体积降了 15%（tree-shaking 更彻底）。主观体验上最大的提升其实是开发时的心流——改一行代码几乎立刻看到结果，这种"快"会实打实地改变你写代码的节奏。