升级Vue2 到 Vue3

2023年年底，vue2 正式地寿终正寝，不再被官方支持。公司业务的后台还有小程序项目都是使用 vue2，早在很早之前就有升级到 vue3 的想法，在我加入团队之前就有其他成员进行尝试，却不了了之。在23年年底前这一规划又被提上日程，当时我便打算拿我们后台的项目开刀，进行这一大更新。

#1、方案调研

作为一个拥有十几万行代码，几百上千个文件的项目，手动一个个去更新，去研究 vue2 语法和 vue3 语法的区别自然是不现实的。既然在当时，vueJs 官方已经把 vue3 作为官方推荐版本有几年的时间了，自然会有许多前人已经为我们铺好了道路。主流的几个方案就有这几个：

• 一个个 vue 文件人工修改（不推荐，重复工作量大，非常容易出错）
• 使用微前端，大项目包小项目，新业务用 vue3 逐步替换旧代码（适用于业务迭代需求紧张情况，小步快跑，完全避免更新对旧代码的影响）
• 使用转换工具，如 GoGoCode（转换工具基于 AST 工具对代码进行替换，有现成的可用方案，基本上生成的 vue3 代码已经高度可用了）

其他说明
Vue 3 官方迁移指南（必读）
vue 官方在官网就已给出非常全面的更新指南，包括推荐更新的工具链（如 vue-route、vue-cli -> vite、Vuex -> Pinia

#2、方案实践

项目中与 vue 更新有关的依赖：vue-cli + Element UI + vue-router + 一些第三方 vue2 组件（富文本编辑器、vueDraggable等）

计划使用 GoGoCode 工具转换的形式升级 Vue

#step_0：更新 cli 工具

我们的项目是由老版本的 vue-cli 工具构建的，因此对于 vue3 需要升级 cli 或者替换为 vite 打包工具，才能获得完整的编译打包工具链支持。（不直接升级 vite 是为了避免在项目中产生过多改动，导致更新过程出现纰漏难以排查的问题。）

复制// 使用 node 工具更新 vue-cli，pnpm yarn 同理
npm update @vue/cli

这一步直接使用 npm 命令，更新 cli 即可，推荐升级到最新版本 cli 工具，同时可以启动项目检查一下是否正确更新。

#step_1：使用 gogocode 工具转换代码

由于写文章的时候 gogocode 官网似乎被劫持了，具体的过程后续补充，可以参考 gogocode_github

• 使用 gogocode 工具转换代码的过程，第一遍转换 vue2 语法至 vue3 语法，第二遍使用提供的 element 转换规则转换 Element-UI 至 Element-plus（如未使用 Element-UI 或使用其他 UI 框架需自行研究实现转换）
• 建议：检查每一个文件变动的代码，避免工具执行出错
• 更新项目 npm 依赖（vue、element、其他第三方 vue 组件等）
• 手动替换使用 v-deep 处理的样式（如果项目中有使用非兼容的语法，也要进行其他的更新）
• 修改 main.js 中挂载根节点方式（改为 createApp）

具体执行代码可以参考其他文章

#step_2：解决一些疑难杂症

到了这一步，基本上就可以使用新的 vue-cli 工具启动基于 vue3 的项目了，这里记录一些踩过的坑。

• 前人写的 vue-router 路由 name 字段重复导致页面路由栈循环调用爆栈，修改即可；
• Element-Plus 的样式和 ELement-UI 有较多差异，具体组件具体调整即可；
• 如果项目无法启动或有一些行为上的错误，可以参考官方迁移文档，配置 vue.config.js 或 main.js 使用 vue2 兼容模式运行项目，逐一排查。

#闲言碎语

总的来说，升级 vue3 的过程已经相对轻松了，vue2 的模板语法在 vue3 中也是可用的，如果是统一使用模板语法写的项目，在 GoGoCode 转换过程中并不会更改很多内容，主要就替换了 v-model emit watch 的一些语法。

更新过程中的主要工作量就在校对 GoGoCode 工具的修改，其对 css 中的一些注释处理有比较严重的问题，实际上用了三天不到，基本上项目就可以正常编译运行了，主要的时间开销是在处理一些 Element 更新带来的样式问题。不过进行校对也是多一层保险，毕竟谁会完全放心把业务代码交给机器来处理呢，用 AI 写代码都要看一眼写的对不对。

在更新后半年多的开发中，切切实实地感受到了 vue3 带来的 setup hooks 写业务的便利，到 3.4 版本后基本上开发中的痛点都完善地差不多了，给尤大点赞。