--- theme: cyanosis ---
Vue 3 已经[发布](https://vue-js.com/topic/5f65624c96b2cb0032c38550)三年，我们有较多项目还停留在 Vue 2。Vue 3 的升级是比较割裂的,我们主要做的是 `2B` 业务，项目、模块、分支都非常多，因此升级的成本和风险都比较高。我们目前的策略是 “新旧并存，渐进式升级”，旧的项目就尽量不变了，新的项目强制使用新的技术栈。利用`微前端`架构，新旧应用可以灵活地组合起来。因此我们的业务组件库、工具库之类需要考虑兼容旧的 Vue 2 项目。这篇文章，就向大家展示我们开发跨版本组件库，其中的决策和实现过程。

## 方案决策实现跨版本的组件都多种方案，下面列举分析几种主要方案：
**方案一：使用 Vue SFC / 模板** 单纯从外观上看 Vue 2 / 3 在模板的语法上[差别并不大](https://v3-migration.vuejs.org/zh/breaking-changes/v-model.html)。在 [Vue 2.7](https://blog.vuejs.org/posts/vue-2-7-naruto) 开始内置了对 `script setup` 也有了较好的支持。理论上，我们可以编写一份代码，然后分别针对 2 / 3 编译两份输出。 ![总体流程如上](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/ea63eb3d7ed14450ada947db2ca0df18~tplv-k3u1fbpfcp-zoom-1.image) 总体流程如上 **笔者提供了一个简单的 DEMO 来验证了这个方案的可行性，详见[这里](https://github.com/wakeadmin/cvv-sfc-demo)。** * 优点 * 模板是 Vue 的第一公民，不需要为了兼容不同版本改变原有的开发习惯。学习成本比较低 * 支持静态编译，比如可以针对不同的版本进行条件编译，**优化包体积**。另外可以**保留[Vue 模板编译优化](https://cn.vuejs.org/guide/extras/rendering-mechanism.html#compiler-informed-virtual-dom)机制**。 * 使用公开标准语法，不需要 hack 或者关心太多框架底层的差异。 * 缺点 * 构建相对复杂，需要两份代码输出。 * 灵活性较差。模板语法差异很小，但不以为着没有差异，当需要处理某些跨版本差异时可能会比较棘手。比如[向下透传事件、props 或者 slots](https://v3-migration.vuejs.org/zh/breaking-changes/render-function-api.html) , [v-bind.sync 废弃了](https://v3-migration.vuejs.org/zh/breaking-changes/v-bind.html) 、[template v-for key](https://v3-migration.vuejs.org/zh/breaking-changes/key-attribute.html)、v-model 协议变化。 * ⚠️ 语法固化，为了兼容 Vue 2，template 语法需要停留在 Vue 3.0，这意味着后续发布的新特性可能无法使用，比如 `defineModel`，`defineOptions`。

**方案 2：渲染函数** Vue 2 和 Vue 3 都支持渲染函数，但是两者之间有非常大的差异。**详细的差异对比可以看笔者整理的这篇文档： [Vue 2/3 渲染函数差异以及兼容方案](https://www.notion.so/Vue-2-3-302cbe0e37794345bbfbd89e32d617db?pvs=21)**
那 Vue 官方的 JSX 插件呢？ Vue 2/3 JSX Babel (**[jsx-vue2](https://github.com/vuejs/jsx-vue2)、[babel-plugin-jsx](https://github.com/vuejs/babel-plugin-jsx)**)插件加了一些语法糖，来简化渲染函数的编写，但是这两个插件的语法完全是两个东西。因此这个方案不在我们的考虑之列。

**方案 3：标准的 JSX** 那为什么不用‘标准’的 `JSX` 呢？使用统一的 JSX 语法，转换为不同版本的渲染函数： ![Untitled](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/a4ca372cbca3451882a2e4d48c5994a8~tplv-k3u1fbpfcp-zoom-1.image) 使用标准的 JSX 语法，意味着： * 不需要任何 `Babel` 插件，能够被市面上主流的编译器(如 tsc， swc，esbuild)直接处理。例如 Typescript CLI: ```json /** tsconfig.json */ { "compilerOptions": { "jsx": "react-jsx", "jsxImportSource": "JSX 运行时名称" } } ``` * 在**运行时**转换到对应版本的渲染函数。 * Typescript friendly。纯 TSX，不需要额外插件(比如 `Volar`)辅助。 * 使用习惯上接近 `React`。 ```diff /** 🔴 1. 事件订阅 **/ // 🤮 - - // 👍 使用 on* 注册时间 + /** 🔴 2. 没有指令 **/ // 🤮 - - - - - ; // 👍 没有语法糖 + + + /** 🔴 3. slots **/ // 🤮 - -

- - - - const scopedSlots = { - header: () =>

, - footer: () => - } - - // 👍 对齐 vue 3 + const App = { + setup() { + const slots = { + bar: () => B, + }; + return () => ( + +

+ + ); + }, + }; /** 🔴 4. 向下透传 props **/ + ```

* 优点 * 构建很简单，使用标准的 JSX 只需构建一次。不需要引入特定的编译器，使用 `Typescript CLI`，`esbuild` 就可以直接编译。 * Typescript Friendly, 不依赖 vue-tsc, 另外相比 `vue-tsc` 编译结果会好一点。 * 灵活性。毋庸置疑，`JSX` 的灵活性，可操行性太强了。 * 相对模板编译来说，可控一点(Hackable)。 * 可以替换官方的 JSX 库，除了本文介绍的`跨版本组件库`场景，在日常 Vue 2/3 应用开发中也可以使用啊。 * 缺点 * 使用 `JSX` 则意味着放弃[模板编译优化](https://cn.vuejs.org/guide/extras/rendering-mechanism.html#compiler-informed-virtual-dom)的机会，比如动态节点标注，预字符串化，缓存，静态提升等等。 * 为了抹平版本之间的差异，多了一层‘运行时’的抽象转换(主要是 Vue 2 上)，会有一些性能损耗。 * 实现上需要熟知两个版本之间的差异性。比较 hack, 可能需要依赖 Vue 的内部实现细节 * 可读性较差，相比 `React` 简洁的 Api，Vue 上的一些特殊的特性，还是会让代码有些不太优雅，例如 Directives、Listeners、Slots 后面我们选择了 `JSX` 方案，因为实现起来更简单，方案更加可控，尤其是应对后续的版本更新。

## 策略构建跨版本的组件库，需要考虑的不仅仅是组件语法问题。Vue 2/3 从底层的 API 到渲染函数、再到应用层的组件库、路由、多语言等等，都出现了割裂。我们得兼顾这些变化。
1. **分层策略** ![Untitled](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/f1dc9eb7d778473795afc3f3c265e82b~tplv-k3u1fbpfcp-zoom-1.image) 我们按照引用关系进行分层： * **`API 层`**。好在 Vue 3 大部分特性(主要是 `Composition API` 和 `defineComponent`) 已经下放到了 Vue 2，我们只需要使用 [vue-demi](https://github.com/vueuse/vue-demi) 就可以无缝使用这些核心的 API。相对应的，上层的组件库、适配器代码禁止直接导入 ‘vue’ * **`视图语法层`**。就如上文说的，我们会封装一个 jsx-runtime, 抹平 Vue 2/3 在渲染函数上的差异。 * **`适配器层`**。应用层的各种库的适配。比如我们公司主要使用 element-ui, 新旧版本的差异会在 element-adapter 中处理，并暴露统一接口。 * **`组件库层`**。最后我们的组件库基于下层提供的抽象能力，实现跨版本。 * **`应用`**。上层的 Vue 2 / 3 应用。下层的适配器，会根据应用使用的 Vue 版本，动态切换适配。

**2) 新版本优先策略** 在封装适配器或者 jsx-runtime 时，当新旧版本出现差异时，我们如何抉择？这里采用的是“新版本优先”的策略，举一些例子： * JSX 的语法对齐 Vue 3 的渲染函数。 * 只使用 Composition API * 只使用 defineComponent 换句话说，如果情况允许，我们始终以 Vue 3 为基准。

**3) 短板优先策略** 短板对齐是实现兼容的基础策略，主要分两个方面： * 削头: 并不是所有 Vue 3 的特性都能下放到 Vue 2, 比如 `Fragment`、`Teleport`、`Suspense`/`await setup`。我们只能放弃这些功能。 * 补尾：针对一些 Vue 2 的短板，需要一些额外的工作，比如针对 [Vue 2 响应式系统的局限性](https://v2.cn.vuejs.org/v2/guide/reactivity.html)，对于数组/对象的修改可能需要显式调用 set 方法。

**4) 回退策略** 对于一些无法抹平的差异，可以按照不同的版本特殊处理。可以使用 vue-demi 的 `isVue2` 来分条件处理。

## 实现 ### API 兼容：vue demi [vue-demi](https://github.com/vueuse/vue-demi) 为实现跨 Vue 版本的库提供基础支持。它的主要策略： * `<=2.6`: 导出 `vue` + `@vue/composition-api`. * `2.7`: 导出 `vue` ( Vue 2.7 内置支持 Composition API). * `>=3.0`: 导出 `vue`, 模拟了 Vue 2 的`set` 、 `del` API. vue-demi 的实现很简单，就是在 npm 的 `postinstall` 钩子中，判断当前环境安装的 vue 库版本，决定导入的库。在我们的场景中，除了 Composition API 和一些基础类型信息还不够，我们 Fork 了 vue-demi 来扩充了一些填充物，进一步抹平一些差异。

### 渲染语法：JSX runtime 的实现 JSX runtime 的实现并不涉及太复杂的技术，主要还是处理渲染函数的繁琐 API 差异。文章篇幅有限，这里我就不展开讲细节了。**⚠️ 完整的差异对比和应对方式可以看这里**：
[**🎉Vue 2 / 3 渲染函数的差异 🎉**](https://www.notion.so/Vue-2-3-302cbe0e37794345bbfbd89e32d617db?pvs=21)
简单来说，我们的 JSX 语法以 Vue 3 为基准，主要涉及事件订阅、slots、指令的转换。
![Untitled](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/7b09bfcdfef24e3e9c3914393d3db40d~tplv-k3u1fbpfcp-zoom-1.image) 具体实现可以看[这里](https://github.com/wakeadmin/tools/tree/main/packages/h)

### 组件定义与 Typescript 支持 Typescript + Volar 就是一门玄学，类型‘体操’几乎占据了开发的三分之一时间。主要问题： * Vue 2/3 类型定义和导出有细微的差别。我们的 jsx-runtime 要求一致的类型。 * JSX 的 slots 不支持类型检查。渲染函数毕竟不是 Vue 的第一公民，slots 在 JSX 下无法类型检查。 * 为了兼容 options API, `defineComponent` 类型定义和推导比较[复杂](https://github.com/vuejs/core/blob/a95e612b252ae59eaf56e0b8ddba66948d4ac20e/packages/runtime-core/src/apiDefineComponent.ts#L44)。 * 泛型组件实现比较复杂，Volar 泛型的支持也比较玄学。 * ...

为了能够更好地创建跨版本的组件，提供更好的类型支持，我们打算简化 `defineComponent`。为了避免命名冲突，尚且命名为 `declareComponent` 吧, 这个函数有以下职责： * 为实现跨版本支持提供必要约束。`declareComponent` 裁剪掉了 `Options API`, 只保留 setup、props、render 等属性。强制走 `Composition API`。 * 为 JSX (比如 v-slots 属性)提供更好类型检查支持 * 同时兼容 vue template 的类型检查 (`volar`)。 * 在运行时抹平一些跨版本的差异。绝大部分差异，Vue 2.7 在 `defineComponent` 方法内部已经抹平了。还有一些 `inheritAttrs` 带来的[隐式差异](https://www.notion.so/Vue-2-3-302cbe0e37794345bbfbd89e32d617db?pvs=21)，**declareComponent 决定直接关闭了 `inheritAttrs`** 。 * 补全短板，并且向下保持兼容。Vue 2 已经不更新了，我们想要支持一些新的特性，比如泛型。
使用示例： ```tsx const Counter = declareComponent({ name: 'Counter', // 定义 props props: declareProps<{ initialValue: number }>( // ⚠️ 和 defineComponent 一样，我们还是需要显式定义 props, 否则会被当做 attrs ['initialValue'] ), // 定义事件 emits: declareEmits<{ change: (value: number) => void }>(), // 定义插槽 // slots: declareSlots<{ foo: { a: number } }>(), // setup setup(props, { emit }) { const count = ref(props.initialValue) const handleClick = () => { count.value++ emit('change', count.value) } return () => (

count: {count.value}

) }, }) ```

为了实现这个目标，我们先来看下 `Volar` 是如何推断组件的类型：
大致的推导过程如下, 其次可以参考 `vue-tsc` 的编译输出或者 Vue `defineComponent` 的类型声明。 ```tsx // https://github.com/vuejs/language-tools/blob/71240c78f1a205605f4c079a299b2701250ef9be/packages/vue-component-type-helpers/index.d.ts#L5 export type ComponentProps = T extends new () => { $props: infer P } ? NonNullable

: T extends (props: infer P, ...args: any) => any ? P : {} export type ComponentSlots = T extends new () => { $slots: infer S } ? NonNullable : T extends (props: any, ctx: { slots: infer S }, ...args: any) => any ? NonNullable : {} export type ComponentEmit = T extends new () => { $emit: infer E } ? NonNullable : T extends (props: any, ctx: { emit: infer E }, ...args: any) => any ? NonNullable : {} export type ComponentExposed = T extends new () => infer E ? E : T extends (props: any, ctx: { expose(exposed: infer E): any }, ...args: any) => any ? NonNullable : {} /** * Vue 2.x */ export type Vue2ComponentSlots = T extends new () => { $scopedSlots: infer S } ? NonNullable : T extends (props: any, ctx: { slots: infer S }, ...args: any) => any ? NonNullable : {} ```
简单来说 `defineComponent` 方法最终输出的组件的类型外观长这样， Volar 会从返回类型中推断 props、emit 等类型： ```tsx type YourComponent = new (...args: any[]): { $props: Props 类型 $emit: 事件类型 $slots: 插槽类型 } ``` > 💡 那 Typescript 的 JSX 怎么对组件进行类型检查呢？这个可以参考 Typescript 的 [JSX 文档](https://www.typescriptlang.org/docs/handbook/jsx.html)，还有 Vue 的 JSX [类型定义](https://github.com/vuejs/core/blob/a95e612b252ae59eaf56e0b8ddba66948d4ac20e/packages/vue/jsx.d.ts#L3)。简单说也是从上述的 `$props` 中推导的。

我们的 `declareComponent` 只要保持和上面的类型兼容，就可以让 `volar` 在 vue template 下进行类型检查了。
因为刨除掉了不必要的 Options API, 相比 defineComponent, 类型定义可以简化很多: ```tsx export function declareComponent< Props extends {} = {}, Emit extends {} = {}, Expose extends {} = {}, Slots extends {} = {} >( options: SimpleComponentOptions ): DefineComponent { /// .. 实现忽略，简单封装 defineComponent } // 🔴 简化 defineComponent API, 只保留 Composition API export type SimpleComponentOptions< Props extends {}, Emit extends {}, Expose extends {}, Slots extends {} > = { name?: string props?: Props emits?: Emit slots?: Slots expose?: Expose setup: ( props: Props, ctx: SetupContext ) => Promise | RenderFunction | void inheritAttrs?: boolean serverPrefetch?(): Promise } export interface ComponentInstance< Props extends {}, Emit extends {}, Expose extends {}, Slots extends {} > { // props 定义 $props: Props & // 🔴 将 emit 转换为 on* 形式，方便 JSX 场景使用 EmitsToProps & { 'v-slots'?: Partial } & { // 🔴 扩展了 v-slots 的定义，方便 JSX 场景使用 'v-children'?: VChildrenType } & { ref?: RefType } // 🔴 支持 volar 推断 slots $slots: Slots // 🔴 支持 volar 推断事件 $emit: EmitFn } // 可以对比 Vue 的 DefineComponent 看看 export interface DefineComponent< Props extends {}, Emit extends {}, Expose extends {}, Slots extends {} > { new (...args: any[]): ComponentInstance } ```
**那怎么支持泛型组件呢？**

### **泛型组件** > Volar 需要升级到最新版本。 > Volar 的泛型支持比较玄学，我建议不要随意尝试！ Vue 3.3 官方正式支持了[泛型 SFC](https://blog.vuejs.org/posts/vue-3-3) 和 defineComponent, 笔者实测 Volar 这块支持还有待改进。但是不妨碍我们进行初步的尝试。上文的 `declareComponent` 写法是不支持泛型组件的。有两种方式可以实现泛型组件的声明，先来看一个比较简单的： 1. **类型断言** ```tsx // 🔴 使用泛型定义 props、emit 和 expose 等类型 interface Props { list: T[] filter: (item: T) => boolean } // 📢 这里要用 type type Emit = { add: (item: T) => void change: (list: T[]) => void } type Expose = { open: (item: T) => void list: T[] } type Slots = { foo: (list: T[]) => any } const GenericBar = declareComponent({ props: declareProps>([]), emits: declareEmits>(), expose: declareExpose>(), slots: declareSlots>(), setup(props, ctx) { expectType(props.list) ctx.emit('change', []) ctx.slots.foo?.([]) ctx.expose({ list: [], open() { // ignore }, }) return {} as any }, // 🔴 重新断言，支持泛型 }) as new (...args: any[]) => ComponentInstance, Emit, Expose, Slots> // 测试 ; { expectType(i) return true }} onAdd={(i) => { expectType(i) }} onChange={(i) => { expectType(i) }} v-slots={{ foo(i) { expectType(i) }, }} > ```
上面的方式在 JSX 表现正常，**但是目前 Volar 在 vue template 并不支持。** > 💡 \*\*这里也有一些冷知识。\*\*假设目标类型约束了 `Index Signature`, 比如 `{[key: string]: Function }`, 那么 `interface` 是无法赋值给它的： > > ```tsx > interface Indexed { > [key: string]: Function > } > > interface Foo { > hello: () => void > } > > declare let a: Indexed > declare let b: Foo > > a = b // 🚨 Index signature for type 'string' is missing in type 'Foo' > ``` > > 如果使用 `type` 创建类型就可以: > > ```tsx > type Bar = { > hello: () => void > } > > declare let c: Bar > a = c // it's work > ``` > > 笔者推测，应该**是 interface 允许 [合并](https://www.typescriptlang.org/docs/handbook/declaration-merging.html#merging-interfaces)，不是静态的，因此不能安全地满足 Index Signature 的约束**。 > > 了解更多： > > [How to fix "Index signature is missing in type" error?](https://stackoverflow.com/questions/60697214/how-to-fix-index-signature-is-missing-in-type-error)

2. **函数形式** Vue 3.3 的 `defineComponent` 新增了一种[函数签名形式](https://cn.vuejs.org/api/general.html#definecomponent)： ```tsx const Comp = defineComponent( (props: { msg: T; list: T[] }) => { // 就像在