Vue 3 迁移指南

值得注意的新特性

Vue 3 中需要关注的一些新特性包括:

• 组合式 API*

• 单文件组件中的组合式 API 语法糖 (<script setup>)*

• Teleport 组件

• Fragments 片段

• Emits 组件选项**

• 来自 @vue/runtime-core 的 createRenderer API 用来创建自定义渲染函数

• 单文件组件中的状态驱动的 CSS 变量 (<style> 中的 v-bind)*

• SFC <style scoped> 新增全局规则和针对插槽内容的规则

• Suspense 实验性

  *现在也支持在 Vue 2.7 中使用
  **Vue 2.7 中支持，但仅用于类型推断

新的框架级别推荐#

Vue 3 的支持库进行了重大更新。以下是新的默认建议的摘要:

• 新版本的 Router, Devtools & test utils 来支持 Vue 3
• 构建工具链: Vue CLI -> Vite
• 状态管理: Vuex -> Pinia
• IDE 支持: Vetur -> Volar
• 新的 TypeScript 命令行工具: vue-tsc
• 静态网站生成: VuePress -> VitePress
• JSX: @vue/babel-preset-jsx -> @vue/babel-plugin-jsx

用于迁移的构建版本

@vue/compat (即“迁移构建版本”) 是一个 Vue 3 的构建版本，提供了可配置的兼容 Vue 2 的行为。

已知的限制

• 基于 Vue 2 内部 API 或文档中未记载行为的依赖。最常见的情况就是使用 VNodes 上的私有 property。如果你的项目依赖诸如 Vuetify、Quasar 或 Element UI 等组件库，那么最好等待一下它们的 Vue 3 兼容版本。
• 对 IE11 的支持：Vue 3 已经官方放弃对 IE11 的支持。如果仍然需要支持 IE11 或更低版本，那你仍需继续使用 Vue 2。
• 服务端渲染：该迁移构建版本可以被用于服务端渲染，但是迁移一个自定义的服务端渲染配置还有很多工作要做。大致的思路是将 vue-server-renderer 替换为 @vue/server-renderer。Vue 3 不再提供一个包渲染器，且我们推荐使用 Vite 以支持 Vue 3 服务端渲染。如果你正在使用 Nuxt.js，可以尝试 Nuxt Bridge，一个 Nuxt.js 2 到 3 的兼容层。对于复杂、生产环境的项目来说，可能更好还是等待一下 Nuxt 3。

非兼容性改变

全局API

• 全局 Vue API 更改为使用应用程序实例
• 全局和内部 API 都经过了重构，现已支持 TreeShaking （摇树优化）

模板指令

• v-model 指令在组件上的使用已经被重新设计，替换掉了 v-bind.sync
• 在<template v-for> 和没有 v-for 的节点身上使用 key 发生了变化
• v-if 和 v-for 在同一个元素身上使用时的优先级发生了变化
• v-bind="object" 现在是顺序敏感的
• v-on:event.native 事件修饰符已经被移除

组件

• 函数式组件只能通过纯函数进行创建
• 单文件组件 (SFC) <template> 标签的 functional attribute 和函数式组件的 functional 选项已被移除
• 异步组件现在需要通过 defineAsyncComponent 方法进行创建
• 组件事件现在应该使用 emits 选项进行声明

渲染函数

• 渲染函数 API 更改
• $scopedSlots property 已移除，所有插槽都通过 $slots 作为函数暴露
• $listeners 被移除或整合到 $attrs
• $attrs 现在包含 class 和 style attribute

自定义元素

• 自定义元素检测现在在模板编译时执行
• 特殊的 is attribute 的使用被严格限制在被保留的 <component> 标签中

其他小改变

• destroyed 生命周期选项被重命名为 unmounted
• beforeDestroy 生命周期选项被重命名为 beforeUnmount
• Props 的 default 工厂函数不再可以访问 this 上下文
• 自定义指令的 API 已更改为与组件生命周期一致，且 binding.expression 已移除
• data 选项应始终被声明为一个函数
• 来自 mixin 的 data 选项现在为浅合并
• Attribute 强制策略已更改
• Transition 的一些 class 被重命名
• <TransitionGroup> 不再默认渲染包裹元素
• 当侦听一个数组时，只有当数组被替换时，回调才会触发，如果需要在变更时触发，则必须指定 deep 选项
• 没有特殊指令的标记 (v-if/else-if/else、v-for 或 v-slot) 的 <template> 现在被视为普通元素，并将渲染为原生的 <template> 元素，而不是渲染其内部内容。
• 已挂载的应用不会替换它所挂载的元素
• 生命周期的 hook: 事件前缀改为 vue:

被移除的 API

• keyCode 作为 v-on 修饰符的支持
• $on、$off 和 $once 实例方法
• 过滤器 (filter)
• 内联模板 attribute
• $children 实例 property
• propsData 选项
• $destroy 实例方法。用户不应该再手动管理单个 Vue 组件的生命周期。
• 全局函数 set 和 delete 以及实例方法 $set 和 $delete。基于代理的变化检测已经不再需要它们了。