Vue 3组件库CDN引入冲突：适配包与CDN双场景需求

问题描述 #

我通过Vite构建的Vue3组件库，在Vue项目中以包形式导入时运行正常，但当Vue与组件库均通过CDN引入时出现冲突，控制台抛出Invalid VNode type: Symbol(v-cmt)警告及Cannot read properties of null (reading 'nextSibling')错误，疑似存在多Vue实例冲突，但已按文档将Vue设为外部依赖，需让组件库同时支持包导入与CDN两种使用场景。

现有配置 #

Vite配置 #

import { defineConfig } from "vite";
import { resolve } from "path";
import vue from "@vitejs/plugin-vue";
import removeAttr from 'remove-attr';

const prod = process.env.NODE_ENV === 'production';

export default defineConfig({
  plugins: [
    vue(),
    removeAttr({
      extensions: [ 'vue' ],
      attributes: prod ?  [ 'data-cy' ] : [],  
  })
  ],
  build: {
    lib: {
      entry: resolve(__dirname, "src/index.js"),
      name: "VueDataUi",
      fileName: "vue-data-ui",
      formats: ['es']
    },
    rollupOptions: {
      external: ["vue"],
      output: {
        globals: {
          vue: "Vue",
        },
      },
    },
    types: [
      {
        declarationDir: "dist/types",
        root: resolve(__dirname, "types"),
        entry: "vue-data-ui.d.ts",
      },
    ],
  },
});

package.json配置 #

{
  "files": [
    "dist"
  ],
  "main": "./dist/vue-data-ui.umd.cjs",
  "module": "./dist/vue-data-ui.js",
  "exports": {
    ".": {
      "import": "./dist/vue-data-ui.js",
      "export": "./dist/vue-data-ui.umd.cjs"
    },
    "./style.css": "./dist/style.css"
  },
  "scripts": {
    "dev": "vite",
    "clean": "node cleanup.cjs",
    "build": "npm run clean && vite build --mode production && node copy-types.cjs",
    "preview": "vite preview",
    "test": "vitest",
    "test:e2e": "npx cypress open"
  }
}

报错信息 #

警告 #

vue.global.js:7963 [Vue warn]: Invalid VNode type: Symbol(v-cmt) (symbol) 
  at <VueUiXy dataset= [{…}] > 
  at <App>

错误 #

Uncaught (in promise) TypeError: Cannot read properties of null (reading 'nextSibling')
    at nextSibling (vue.global.js:9029:33)
    at te (vue.global.js:6241:18)
    at g (vue.global.js:5080:24)
    at M (vue.global.js:5415:15)
    at R (vue.global.js:5323:15)
    at $ (vue.global.js:5192:15)
    at g (vue.global.js:5109:23)
    at ve.fn (vue.global.js:5716:19)
    at ve.run (vue.global.js:568:31)
    at ks (vue.global.js:8080:38)

解决方案 #

一、构建步骤调整（推荐，从根源解决） #

1. 生成多格式构建产物

修改Vite配置中build.lib.formats，同时生成ES和UMD格式，UMD格式天然适配全局CDN场景：

build: {
  lib: {
    entry: resolve(__dirname, "src/index.js"),
    name: "VueDataUi",
    fileName: "vue-data-ui",
    formats: ['es', 'umd'] // 添加umd格式
  },
  // ...其他配置不变
}

2. 优化Rollup输出配置

确保所有格式的产物都正确外部化Vue，并映射到全局Vue变量：

rollupOptions: {
  external: ["vue"],
  output: [
    {
      format: 'es',
      globals: { vue: 'Vue' },
      paths: {
        // 让ES模块在浏览器中可回退到全局Vue（可选，若用户未提供importmap）
        vue: 'https://cdn.jsdelivr.net/npm/vue@3.2.19/+esm'
      }
    },
    {
      format: 'umd',
      name: 'VueDataUi',
      globals: { vue: 'Vue' }
    }
  ]
}

3. 调整package.json导出规则

添加browser字段，让浏览器环境优先加载UMD包：

"exports": {
  ".": {
    "import": "./dist/vue-data-ui.js",
    "require": "./dist/vue-data-ui.umd.cjs",
    "browser": "./dist/vue-data-ui.umd.cjs" // 浏览器环境优先用UMD
  },
  "./style.css": "./dist/style.css"
}

4. 入口文件兼容全局Vue

在组件库入口src/index.js中添加全局Vue的兼容逻辑，确保组件使用的是同一个Vue实例：

// 优先使用全局Vue，否则导入模块版Vue
const Vue = typeof window !== 'undefined' && window.Vue ? window.Vue : await import('vue');

import VueUiXy from './components/VueUiXy.vue';

export { VueUiXy };

// 若支持插件式注册，同时导出插件
export default {
  install(app) {
    app.component('VueUiXy', VueUiXy);
  }
};

二、用户端临时解决办法（无需修改组件库） #

方案1：使用UMD版本组件库

直接引入组件库的UMD版本，它会自动使用全局Vue实例：

<script src="https://cdn.jsdelivr.net/npm/vue@3.2.19"></script>
<!-- 引入UMD版本组件库 -->
<script src="https://cdn.jsdelivr.net/npm/vue-data-ui@1.9.4/dist/vue-data-ui.umd.cjs"></script>

<script>
  const { createApp } = Vue;
  createApp({
    components: {
      'vue-ui-xy': VueDataUi.VueUiXy // 从全局对象获取组件
    },
    // ...其他配置
  }).mount('#app');
</script>

方案2：使用Import Map统一Vue实例

通过importmap让ES模块导入的vue指向CDN的ES版本，确保组件库与项目使用同一个Vue实例：

<head>
  <script type="importmap">
    {
      "imports": {
        "vue": "https://cdn.jsdelivr.net/npm/vue@3.2.19/+esm"
      }
    }
  </script>
  <!-- 移除全局Vue的script，改用模块导入 -->
</head>
<body>
  <div id="app"></div>

  <script type="module">
    import { createApp } from 'vue';
    import { VueUiXy } from 'https://cdn.jsdelivr.net/npm/vue-data-ui@1.9.4/+esm';
    
    createApp({
      components: { 'vue-ui-xy': VueUiXy },
      // ...其他配置
    }).mount('#app');
  </script>
</body>

内容的提问来源于stack exchange，提问作者alec_lloyd_probert