从零到一：构建企业级 Vue.js 3 组件库

前言：为何要构建组件库？

在现代前端工程化体系中，组件库已不再是大型团队的专属。它是一个团队设计规范、开发模式和技术沉淀的核心载体。构建一个组件库，能够带来诸多优势：

• 提升效率：提供可复用的高质量组件，避免团队成员重复"造轮子"，显著提升开发效率。
• 统一体验：作为设计系统（Design System）的技术落地，确保产品在视觉和交互上的一致性。
• 保障质量：经过充分测试的组件，能够有效减少项目中因组件质量问题引发的 Bug。
• 促进协作：为开发和设计团队提供一个共同的沟通语言和协作平台。

本文将引导你采用现代化工具链，从零开始构建一个具备企业级标准和良好开发体验的 Vue 3 组件库。

1. 架构设计：Monorepo 与 pnpm Workspace

对于组件库这类多包项目（例如：组件包、工具函数包、Hooks 包、文档站），Monorepo (单体仓库) 是当前社区公认的最佳实践。它允许我们在单一 Git 仓库中管理多个相互独立的 npm 包，极大地简化了跨包调试、依赖管理和版本发布的流程。

pnpm 提供的 workspace 功能，是实现 Monorepo 的一种轻量且高效的方式。

1.1. 初始化项目

首先，全局安装 pnpm：

npm install -g pnpm

在项目根目录执行初始化：

pnpm init

修改生成的 package.json，将其声明为私有，因为它仅作为整个工作区的管理容器，无需发布。

{
  "private": true,
  "version": "1.0.0",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  }
}

1.2. 规划目录结构并配置工作区

一个典型的组件库 Monorepo 结构如下：

.
├── packages/                  # 存放所有源码包
│   ├── components/            # Vue 组件
│   ├── hooks/                 # Composition API Hooks
│   └── utils/                 # 通用工具函数
├── docs/                      # 文档站（例如 VitePress）
├── examples/                  # 用于本地调试和展示的示例项目
├── pnpm-workspace.yaml        # pnpm 工作区配置文件
└── package.json               # 根 package.json

在根目录创建 pnpm-workspace.yaml 文件，pnpm 会根据此文件识别工作区中的项目：

packages:
  - 'packages/**'
  - 'docs'
  - 'examples'

1.3. 配置子包 (Package)

工作区内的每个子项目都是一个独立的 npm 包，拥有自己的 package.json。以 packages/components 为例：

{
  "name": "uv-ui",
  "version": "1.0.0",
  "private": false,
  "description": "A Vue.js 3 component library.",
  "main": "dist/lib/index.js",
  "module": "dist/es/index.js",
  "style": "dist/es/style.css",
  "types": "dist/es/index.d.ts", 
  "scripts": {
    "build": "vite build"
  },
  "files": [
    "dist"
  ],
  "keywords": ["vue", "component", "ui"],
  "author": "your-name",
  "license": "MIT",
  "dependencies": {
    "@uv-ui/hooks": "workspace:*",
    "@uv-ui/utils": "workspace:*"
  },
  "peerDependencies": {
    "vue": "^3.2.0"
  }
}

最佳实践：

• @uv-ui/hooks": "workspace:*"：workspace:* 协议是 pnpm 的核心特性。它会确保 uv-ui 直接依赖于工作区内 hooks 包的源码，实现无缝的实时联调，而无需手动 link 或发布。
• peerDependencies：对于组件库，vue 应该是对等依赖（Peer Dependency），而不是生产依赖（Dependency）。这意味着我们的组件库期望宿主项目（使用它的项目）来提供 Vue 的实例。这可以有效避免因版本冲突或重复打包导致的运行时错误。

2. 组件开发：规范与模式

2.1. 组件注册工具：withInstall

为了让组件既能通过 app.use() 全局安装，又能被单独按需引入，我们可以创建一个 withInstall 高阶函数。

// packages/utils/withInstall.ts
import type { App, Plugin } from 'vue'

export type SFCWithInstall<T> = T & Plugin

export const withInstall = <T>(comp: T) => {
  (comp as SFCWithInstall<T>).install = (app: App) => {
    // 注册为全局组件
    app.component((comp as any).name, comp)
  }
  return comp as SFCWithInstall<T>
}

2.2. 组件实现与导出

遵循"单一职责"原则，每个组件在自己的目录中开发，并通过 index.ts 对外暴露。

packages/components/
└── src/
    ├── button/
    │   ├── button.vue
    │   └── index.ts
    └── index.ts      # 统一导出所有组件

button/index.ts:

// packages/components/src/button/index.ts
import Button from './button.vue'
import { withInstall } from '@uv-ui/utils'

export const UvButton = withInstall(Button) // 包装 install 方法
export default UvButton

index.ts (统一出口):

// packages/components/src/index.ts
import { UvButton } from './button'

export default {
  install: (app) => {
    app.use(UvButton) // 全局安装时，注册所有组件
  }
}

export * from './button' // 按需导出

2.3. 组件编码与样式方案

在 button.vue 中，我们采用 <script setup> 语法糖，但需保留一个独立的 <script> 块来定义组件 name，这对于插件注册和开发者工具调试至关重要。

<!-- packages/components/src/button/button.vue -->
<template>
  <button class="uv-button">
    <slot />
  </button>
</template>
<script lang="ts" setup>
// defineProps, defineEmits, etc.
</script>
<script lang="ts">
export default {
  name: 'UvButton' // 组件注册名
}
</script>
<style lang="scss">
// 使用 BEM 规范，避免样式冲突
.uv-button {
  // ...
}
</style>

样式最佳实践：设计令牌 (Design Tokens)
强烈建议使用 CSS 自定义属性（CSS Variables）来管理颜色、字体、间距等基础样式值。这些变量被称为"设计令牌"，它们是设计系统在代码中的直接体现，能极大地简化主题定制和维护工作。

此外，组件库的样式通常不应使用 scoped，以方便用户覆盖。通过 BEM 命名规范和统一的类名前缀（如 uv-）可以有效避免样式冲突。

:root {
  --uv-color-primary: #409eff;
  --uv-font-size-base: 14px;
  --uv-border-radius-base: 4px;
}

.uv-button {
  background-color: var(--uv-color-primary);
  font-size: var(--uv-font-size-base);
  border-radius: var(--uv-border-radius-base);
}

3. 构建与打包：Vite 库模式深度解析

Vite 的库模式（Library Mode）为我们提供了强大而简洁的打包能力。核心配置在于 vite.config.ts。

// packages/components/vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import dts from 'vite-plugin-dts'

export default defineConfig({
  build: {
    target: 'modules',
    outDir: 'dist',
    minify: true,
    rollupOptions: {
      // 确保外部化处理那些你不想打包进库的依赖
      external: ['vue'],
      input: ['src/index.ts'],
      output: [
        {
          format: 'es',
          entryFileNames: '[name].js',
          dir: 'dist/es',
          // 让打包目录和我们源文件目录对应
          preserveModules: true,
          preserveModulesRoot: 'src',
        },
        {
          format: 'cjs',
          entryFileNames: '[name].js',
          dir: 'dist/lib',
          preserveModules: true,
          preserveModulesRoot: 'src',
        }
      ]
    },
    lib: {
      entry: 'src/index.ts',
      name: 'UvUi'
    }
  },
  plugins: [
    vue(),
    // 用于生成 .d.ts 类型声明文件
    dts({
      outDir: ['dist/es', 'dist/lib'],
      // 指定根目录，确保在此目录下生成 .d.ts 文件
      entryRoot: 'src'
    })
  ]
})

核心配置解析:

• external: ['vue']: 这是最重要的配置之一。它告诉 Vite 不要将 vue 打包进我们的库中，而是作为外部依赖处理，由宿主环境提供。
• preserveModules: true: 这是实现按需加载的关键。它会保留原始的模块结构，而不是将所有代码打包成一个文件。
• output 数组: 我们配置了两种输出格式：es (ESM) 和 lib (CJS)，以兼容不同的模块系统。
• vite-plugin-dts: 对于一个 TypeScript 组件库，类型声明文件 (.d.ts) 是必不可少的。这个插件可以自动根据源码生成类型定义。

4. 发布与版本管理

4.1. 发布到 NPM

1. 登录 npm:

npm login

1. 添加 prepublishOnly 脚本:
   为了防止发布未经构建的代码，可以在 package.json 中添加一个 prepublishOnly 脚本。它会在 npm publish 执行前自动运行。

  "scripts": {
    "build": "vite build",
    "prepublishOnly": "npm run build"
  }

1. 发布:
   在子包的根目录（如 packages/components）下执行：

npm publish

如果发布的是带 scope 的包 (如 @org/name)，需要指定公共访问权限：

npm publish --access=public

4.2. 版本管理：语义化版本 (SemVer)

强烈建议遵循语义化版本（SemVer）规范。npm version 命令是管理版本的最佳工具，它会自动修改版本号并创建 Git 标签。

• 修复 Bug (补丁版本): 1.0.0 -> 1.0.1

npm version patch

• 新增功能 (次版本): 1.0.1 -> 1.1.0

npm version minor

• 破坏性变更 (主版本): 1.1.0 -> 2.0.0

npm version major

更新版本后，再执行 npm publish。

5. 文档化：VitePress

一个优秀的组件库离不开清晰的文档。VitePress 是 Vue 官方出品的静态站点生成器（SSG），它天生支持在 Markdown 中直接使用 Vue 组件，是为组件库编写文档的最佳选择。

在 docs 目录下进行安装和配置：

pnpm add -D vitepress vue

一份好的文档应至少包含：

• 设计理念和原则
• 快速上手指南
• 每个组件的详细用法、API (Props, Events, Slots) 和代码示例。

具体使用方法请参考 VitePress 官方文档。

至此，我们完整地走过了一个企业级 Vue 3 组件库从设计、开发、构建到发布的全部流程，有其他问题可以一起探讨