vue-demi：一套代码完美兼容 Vue2/Vue3 的终极方案

在vue生态中,很多开发者都会遇到一个头疼的问题: Vue2 和 Vue3的Composition API语法,导入路径,生命周期存在大量差异

如果我们开发组件库,工具库,公共Hooks,想要同时支持Vue2 和 Vue3,常规方案只有两种:

• 维护两套代码,分别适配两个版本,成本翻倍,迭代繁琐
• 通过大量条件判断做版本兼容,代码冗余,可读性极差

而 vue - demi 就是为解决这个痛点而生的神器,它可以让我们只写一套代码,自动适配Vue2,Vue2.7,Vue3全版本,是目前Vue 跨版本开源库的通用解决方案

一、什么是 vue-demi？

1.核心定义

vue-demi是一个轻量的 Vue 版本兼容工具库，名字中的demi源自法语，意为“一半、半个”，寓意它是衔接 Vue2 和 Vue3 的中间层、兼容层。

官方定位：Creates Universal Library for Vue 2 & 3（为 Vue2、Vue3 构建通用库）。

简单来说：开发者只需要按照 Vue3 Composition API 规范写一套代码，vue-demi 会自动根据用户项目的 Vue 版本，适配对应语法和 API，无需手动处理版本差异。

2. 解决的核心问题

Vue多版本最大的兼容痛点集中在APi导入和语法差异:

• Vue3 : 组合式API 从 vue直接导入(ref,reactive,watch,onMounted等)
• Vue2.6: 及一下: 无原生组合式API,需要依赖@vue/composition-api插件
• Vue2.7: 内置组合API,但部分导出逻辑和Vue3存在细微差异, Vue-demi抹平了这所有差异,提供统一的导入入口和一致的运行行为

二、vue-demi 核心工作原理

1. 版本自动检测

当你安装vue-demi时，它会触发postinstall钩子，自动扫描当前项目的 Vue 版本，区分三种场景：

• Vue ≤ 2.6：自动依赖@vue/composition-api，导出兼容 Vue2 的组合式 API

• Vue = 2.7：使用 Vue2.7 内置的组合式 API，无需额外依赖

• Vue ≥ 3.0：直接使用 Vue3 原生 API，完全适配 Vue3 语法

2. 统一 API 入口

无论用户项目是哪个 Vue 版本，你的业务代码永远只需要从 vue-demi 导入 API，无需区分环境：

摒弃繁琐的环境判断：

// 无需这样写！冗余且难维护 import { ref } from (Vue3 ? 'vue' : '@vue/composition-api')

统一优雅写法：

// 一套代码通吃所有版本 import { ref, reactive, watch, onMounted } from 'vue-demi'

3. 无侵入、零运行开销

vue-demi 只是构建时的适配层，不会侵入业务代码，运行时无额外开销，打包后会自动替换为对应 Vue 版本的原生 API，性能和原生写法完全一致。

三、vue-demi 适用场景

vue-demi不适合普通业务项目，它的核心价值在于库开发，精准适配以下场景：

• 开发通用 Vue 组件库（需要同时支持 Vue2/Vue3）

• 开发 Vue 工具库、Hooks 库、指令库、插件

• 维护需要兼容多版本 Vue 的开源项目

• 企业内部通用公共组件、公共逻辑库，适配多版本业务项目

四. 使用教程

1. npm install vue-demi -S

安装完成后,postinstall 钩子会自动检测Vue版本,完成适配配置,无需手动操作

2. 编写通用兼容代码

我们编写一个通用的useCount计数器 Hooks，这套代码可直接在 Vue2、Vue3 项目中运行：

// src/useCount.js // 统一从 vue-demi 导入 API import { ref, computed } from 'vue-demi' export function useCount(initialValue = 0) { // 响应式数据 const count = ref(initialValue) // 计算属性 const doubleCount = computed(() => count.value * 2) // 方法 const increment = () => { count.value++ } const decrement = () => { count.value-- } return { count, doubleCount, increment, decrement } }

3. 多版本项目测试

在 Vue2 项目、Vue3 项目中直接引入上述 Hooks，无需任何修改，直接可用

// 任意 Vue 版本项目中使用 import { useCount } from './useCount' export default { setup() { const { count, doubleCount, increment } = useCount(10) return { count, doubleCount, increment } } }

五.常见坑与避坑指南

1. 业务项目无需安装

vue-demi 是库开发工具，普通业务项目直接用对应版本原生 API 即可，安装后毫无意义，还会增加冗余依赖。

2. 禁止混用原生 API 和 demi API

开发兼容库时，所有组合式 API 必须全部从 vue-demi 导入，禁止部分从vue、部分从vue-demi导入，会导致版本冲突、响应式失效。

3. Vue2.7 特殊适配

Vue2.7 内置组合式 API，但部分边界逻辑和 Vue3 不同，vue-demi 已做抹平处理，不要手动安装 @vue/composition-api，会造成版本覆盖冲突。

4. 打包配置注意事项

使用 vite/webpack 打包兼容库时，需要将vue-demi设为外部依赖（external），避免打包进产物，保证用户项目动态适配版本：

// vite.config.js export default { build: { rollupOptions: { external: ['vue', 'vue-demi'] } } }