如今 Vue 3 的生态已经逐渐成熟,Vue 2 及相关的配套也都逐渐停止更新,是适合升级的时候了。
Vue 3 的语法还是很容易上手的,对于新项目来说,使用起来没什么问题,也挺好用,但对于 Vue 3 老项目,升级的过程还是稍微有些折腾。
Vue CLI 升级为 Vite
Vue CLI 新版也支持 Vue 3,但毕竟它已经不再更新了,既然升级,还是换成 Vite 吧。
通过 npm init vue@latest
创建 Vue 3 项目,然后将 vite.config.ts
及 eslint 、.eslintrc.cjs
.prettierrc.json
等基础文件复制到项目中。
更新后发现 eslint 无法自动修复格式化的内容了,从 eslint 配置文件看到,有一个 @vue/eslint-config-prettier/skip-formatting
设置。
而新版的 package.json 里有一个脚本: "format": "prettier --write src/"
,看来新版把主要的格式化工作交给 prettier 执行了。
其他的 Vite 设置,在此前 React 项目升级中已有记录: react-scripts 项目升级至 vite
Vue 更新
Vue 提供了一份迁移文档: https://v3-migration.vuejs.org/zh/
列举的非兼容改动还是比较多的,也会产生较多的代码改动量,比如:
- 全局 API 应用实例
- v-model 改为
modelValue
和update:modelValue
事件的交互 - 统一了普通插槽和作用域插槽,需修改 slot 相关旧用法
$listeners
合并到$attrs
- 移除 v-on.native 修饰符
$on
,$off
和$once
实例方法已被移- 移除了过滤器
- ...
VSCode 需要安装新版的插件:
- Vue Language Features (Volar) - 必选
- TypeScript Vue Plugin (Volar)
如果需要使用 TS,要安装以上两个两个插件,安装后 VSCode 才能识别引入的 Vue 单文件相关类型。同时,项目的 npm 依赖 typescript 也需要更新到最新版,才能正确识别选项式 API 的类型。
Vue Router
迁移文档: https://router.vuejs.org/zh/guide/migration/
总体来说,改动量不大,通过以下格式创建实例:
const router = createRouter({
history: createWebHistory(import.meta.env.BASE_URL),
routes: []
})
app.use(router)
另外,transition 和 keep-alive 现在必须通过 v-slot API 在 RouterView 内部使用。
Vuex 升级为 pinia
Pinia 比起 Vuex 更适合组合式 API,对 TS 的支持更好,也是 Vue 未来主推的首选状态管理库。
从 Vuex 迁移: https://pinia.vuejs.org/zh/cookbook/migration-vuex.html
mutations
移除了,合并到actions
里了actions
可以通过this
获取数据,不需要再接收state
参数$store
对象没有了,需要用到的地方通过mapState
获取数据
第三方库升级
第三方库才是 Vue 2 升级 Vue 3 最繁琐的地方。
有些未支持 Vue 3 的库,需要自研或寻找其他的替代包,这个会阻碍升级进程。
另外,如果用到第三方 UI 库,比如 vant / element-plus 等,变动的细节很多,而我们往往也是整个项目贯穿大量使用,这时候就得每个组件去核对它的 API,结合各个库提供的破坏性改动文档,然后逐个用到的地方找出来不断修改。
- element-plus 的改动点: https://github.com/element-plus/element-plus/discussions/5657
- vant 的改动点:查看文档“从 v2 升级到 v3”、“从 v3 升级到 v4”
比如 v-model 在这些库里变成了各式各样的 v-model:value
、 v-model:show
、v-model:open
等,细节很多,以及这些第三方库内部的样式也会发生变化,也得确认升级后的样式是否正确,尤其是使用了 :deep() 去重置样式的地方。
由于每个第三方库升级的方法各不相同,这里不逐一记录了,它们官网往往也都会有迁移指南。
使用工具辅助升级
对于大型项目,手动升级工作量比较大,可以借助 gogocode-plugin-vue 和 gogocode-element-plugin 等工具将 vue 和 element 的语法进行升级。
然后再结合手工分别对改动的内容进行 code review ,再整体启动项目,调试各个功能是否正常。