从零到一：用 Vue 打造一个零依赖、插件化的 JS 库

你是否曾想过，除了开发复杂的单页应用（SPA），我们还能用 Vue 做些什么？比如，开发一个像地图 SDK、在线客服或数据统计脚本那样的独立 JS 库？用户只需在页面上引入一个 <script> 标签，就能立即使用你提供的功能，而无需关心其内部实现。

今天，我们就来探讨如何使用 Vue 和 Vite，从零开始构建一个这样的 JS 库。

一、需求分析：我们想做什么？

我们的目标非常明确，创建一个名为 phpreturn 的库，它需要满足以下条件：

最终产物单一：打包后只有一个 JS 文件，例如 phpreturn.js。
使用简单：终端用户只需通过 <script src="phpreturn.js"></script> 引入，无需安装任何依赖或额外引入 Vue。
全局 API：引入后，在 window 对象上挂载一个全局变量（如 phpreturn），通过 phpreturn.chooseUser() 等方法调用功能。
UI 驱动：调用方法后，会弹出由 Vue 组件构成的 UI 界面（如一个用户选择弹窗）。
环境无关：无论是在一个普通的静态 HTML 页面，还是在一个已经使用 Vue 2 或 React 的复杂项目中，这个库都必须能正常工作，且不产生任何冲突。

二、核心要点与挑战：如何实现？

要满足上述需求，我们必须解决两个核心问题：打包和隔离。

打包 (Bundling) 我们希望交付的是一个“全家桶”文件，包含了 Vue 运行时和我们所有的业务组件。这意味着在打包时，不能像开发普通 Vue 插件那样将 Vue 设置为外部依赖（external）。我们需要告诉打包工具（Vite）：“把 Vue 和我的代码一起打包进去！”
隔离 (Isolation) 这是最大的挑战。如果我们的库被引入一个已经存在 Vue 的页面，会发生什么？ JS 冲突：可能会出现两个不同版本的 Vue 实例，导致全局状态污染或方法覆盖。 CSS 冲突：我们的组件样式可能会影响宿主页面，反之亦然。.btn 或 .container 这种通用类名简直是灾难的根源。解决方案：Shadow DOM。 Shadow DOM 是 Web Components 技术的一部分，它允许我们将一块独立的、封装的 DOM 树附加到普通元素上。这块 DOM 树（包括其内部的 HTML 和 CSS）与主文档的 DOM 完全隔离，形成了一个完美的“沙箱”。我们的 Vue 应用将在这个沙箱中运行，从而彻底解决了 JS 和 CSS 的冲突问题。

三、实现方式：一步步构建 phpreturn

让我们通过具体的代码来实现这个想法。

步骤 1：初始化 Vite 项目

首先，我们需要一个基础的 Vue + Vite 项目。打开你的终端，运行以下命令来创建项目：

npm create vite@latest phpreturn -- --template vue

进入项目目录并安装依赖：

cd phpreturn

npm install

这会创建一个名为 phpreturn 的新目录。为了保持项目整洁，我们可以清理一下 Vite 生成的默认文件：

删除 src/assets 目录。
删除 src/components/HelloWorld.vue 和 src/App.vue 文件。
清空 src/main.js 的内容，准备编写我们的库入口逻辑。

现在，我们的项目已经准备就绪。

步骤 2：配置 Vite 进行独立打包

接下来，修改项目根目录下的 vite.config.js，告诉 Vite 我们要构建一个库（library），而不是一个应用。

// File: vite.config.js
import {
   
    defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import path from 'path'

export default defineConfig({
   
   
  plugins: [vue()],
  // 新增：在开发模式下，模拟 UMD 挂载到 window
  define: {
   
   
    'process.env.NODE_ENV': JSON.stringify(process.env.NODE_ENV),
  },
  build: {
   
   
    lib: {
   
   
      entry: path.resolve(__dirname, 'src/main.js'),
      name: 'phpreturn',      // 挂在 window 上的全局变量名
      formats: ['umd'],   // 输出 UMD 格式，兼容 <script> 标签
      fileName: () => `phpreturn.js` // 固定输出文件名
    },
    // 注意：这里没有 rollupOptions.external，意味着所有依赖（包括Vue）都会被打包进去
  }
})

步骤 3：创建与 Shadow DOM 结合的入口文件

src/main.js 是我们库的灵魂。它负责创建 Shadow DOM 环境，定义全局 API，并将 Vue 组件挂载进去。

// File: src/main.js
import {
   
    createApp } from 'vue';
import ChooseUser from './components/ChooseUser.vue';

// 核心函数：在 Shadow DOM 中挂载组件
function mountInShadowDom(component, props) {
   
   
  const hostElement = document.createElement('div');
  document.body.appendChild(hostElement);

  const shadowRoot = hostElement.attachShadow({