Vue3组件库设计实战：从架构分层到按需加载的工程实现

Vue3组件库设计是前端工程能力的分水岭。业务迭代中反复出现的表格、表单、弹窗，与其散落在各项目里复制粘贴，不如沉淀成统一组件库。一个可维护的组件库要解决四个问题：目录架构、组件通信规范、主题定制机制、按需加载构建。本文以Composition API为基础展开组件库的完整搭建路径。

组件库架构分层：core、theme与构建物的边界划分

推荐三层结构：组件逻辑层、样式主题层、构建产物层。目录参考：

ui-library/
├── packages/
│   ├── core/          # 组件源码与逻辑
│   │   ├── components/
│   │   │   ├── button/
│   │   │   ├── table/
│   │   │   └── index.ts
│   │   └── composables/   # useTable、useForm等
│   └── theme-chalk/  # 样式变量与SCSS
├── scripts/build.mjs
└── package.json

逻辑与样式分离的价值在定制项目：换肤只改theme包，组件行为不动。composables放跨组件复用的逻辑，如useFormDraggable、useTableSelection，这是组件库对外输出的第二资产。

组件通信设计：defineExpose与provide/inject的取舍

组件库通信遵循三条规则：父子用props/emit，跨层级依赖用provide/inject，实例方法用defineExpose白名单暴露。

<MyTable ref="tableRef" :columns="columns" :data="rows" />

// 组件内部：只暴露受控方法
defineExpose({
  clearSelection: () => state.selected.clear(),
  toggleRowSelection: toggleRow
})

// 使用方通过ref调用
tableRef.value.clearSelection()

provide/inject适合传递上下文（如Form向所有FormItem注入校验器），注意用InjectionKey泛型标记保持类型提示。defineExpose只暴露必要方法，内部状态全部收口，否则使用方会依赖实现细节，组件库升级就是灾难。

主题定制：CSS变量与SCSS变量的双轨方案

CSS运行时变量负责主题切换，SCSS编译期变量负责尺寸间距：

:root {
  --ui-color-primary: #409eff;
  --ui-border-radius: 4px;
}
.my-button--primary {
  background: var(--ui-color-primary);
}

/* 暗色模式切换 */
html[data-theme="dark"] {
  --ui-color-primary: #79bbff;
}

使用方覆盖–ui-*变量即可实现换肤，无需重新编译。SCSS变量（$spacing-sm）只处理与视觉规范绑定的编译期决策，两者职责不要混用。

按需加载与Tree-shaking：sideEffects与产物格式

组件库必须支持tree-shaking，package.json配置是关键：

{
  "name": "my-ui",
  "main": "dist/my-ui.es.js",
  "module": "dist/my-ui.es.js",
  "sideEffects": ["dist/**/style/**", "*.scss"]
}

构建用Vite的library模式，external掉vue避免产物重复打包。样式按需引入交给unplugin-vue-components的resolver自动处理：

import Components from 'unplugin-vue-components/vite'
import { MyUIResolver } from 'my-ui/resolver'

plugins: [
  Components({ resolvers: [MyUIResolver()] })
]

样式文件标sideEffects防止被tree-shaking误删——这是组件库构建最高频的翻车点，页面引入组件却没样式，十有八九是这里没声明。

组件质量保障：文档、单测与版本策略

文档用VitePress搭建，每个组件的demo即测试用例，交互示例可直接复制。单测Vitest跑逻辑层，Playwright做关键交互的E2E。版本遵循semver：破坏性变更升主版本，新增组件升次版本，修复升修订号，CHANGELOG逐条记录。发布前跑一遍size-limit，防止单个组件体积膨胀影响使用方构建产物。