上周一个刚入职不久的后端同事跑来问我“我看你们前端项目里Button、Input这些组件自己写一套好像也不难为什么还要花时间搞一个独立的组件库直接用现成的Element Plus或者Ant Design Vue不香吗”我给他看了我们内部组件库的文档站点开一个复杂表格组件的“高级筛选”面板。这个面板集成了几十种字段类型、支持动态表单配置、与后端接口自动联调并且样式和交互与我们所有中后台产品保持高度一致。“你看这个组件”我说“它在我们公司五个不同的业务系统中都在用。如果每个项目都自己实现一遍先不说开发成本光是后续加一个‘时间范围快捷选择’的功能五个项目就要改五次测试五遍还可能产生五种不同的交互细节。而现在我们只需要在组件库里更新一版所有项目升级依赖就都有了。”他若有所思“所以自己搞组件库不是为了‘造轮子’而是为了‘统一轨道’”这个比喻很精准。对于大多数业务团队而言从零开发一个对标开源巨头的通用UI库既不现实也无必要。真正的价值在于针对自身业务的高频、复杂场景沉淀出一套标准化的解决方案。这不仅能提升开发效率更能从根本上保障产品体验的一致性降低长期的维护成本。Vue 3.4 带来了性能的显著提升和开发者体验的优化正是重新思考并实践“业务组件库”的好时机。本文将抛开那些华而不实的噱头聚焦于一个核心目标如何从零开始搭建一个真正能在生产环境落地、并随着业务演进的 Vue 3 UI 组件库。我们不追求大而全而是追求可用、可维护、可复用。1. 起点想清楚你要解决什么问题再动手在敲下第一行代码之前必须回答几个关键问题。方向错了后面所有努力都可能白费。1.1 目标是“学习玩具”还是“生产工具”这是首要问题它决定了整个项目的技术选型、工程结构和质量标准。学习玩具目标是理解组件库的基本原理。可以只关注组件的props、slots、emits设计用 Vite 跑个示例看看效果就足够了。工程上可以极简。生产工具目标是服务于真实项目。这就必须考虑如何打包发布需要输出多种模块格式ES Module, CommonJS吗需要打包成单文件还是按需引入类型支持TypeScript 声明文件.d.ts如何生成和管理样式处理CSS 是单独输出还是内联如何支持主题定制如何处理 CSS 作用域问题文档与演示如何让使用者包括未来的你自己快速理解组件用法版本与发布如何管理版本号如何发布到私有或公共仓库测试单元测试、组件测试如何集成我们的讨论将完全基于“生产工具”这个目标展开。只有用生产级的标准来要求这个过程学到的东西才有长期价值。1.2 范围是“基础组件”还是“业务组件”组件库的范畴很大需要明确第一阶段的核心。基础组件如 Button、Input、Select、Modal、Table 等。它们功能相对独立与业务逻辑耦合度低。造这类轮子更多是与开源库竞争挑战在于设计、交互细节和性能优化。业务组件如“数据概览卡片”、“高级搜索面板”、“审批流程展示器”等。它们深度结合特定业务逻辑开源库通常不提供。这类组件的价值最高是团队提效的关键。一个务实的建议是从“基础组件”中挑选几个最常用、且你对其实现有自己想法的开始同时规划一个典型的“业务组件”作为目标。例如先实现 Button、Input、Modal然后用它们来拼装一个“用户选择器”业务组件。这样既能练手基础又能立刻感受到组件复用的威力。1.3 设计有“设计规范”吗没有设计规范的组件库就像没有图纸的建筑工地。样式会逐渐失控组件之间无法和谐共处。在开始前你需要确定或制定一些基本的设计 Token色彩系统主色、成功色、警告色、错误色、一系列中性灰。字体系统字体家族、字号、字重、行高。间距系统基于一个基数如 4px 或 8px的间距尺度。圆角、阴影、动效曲线等。即使最初很简单也要形成文档。这能保证你写的第一个 Button 和第一百个 Table在视觉语言上是同源的。2. 搭建用现代工具链构筑坚实工程地基确定了目标我们开始动手。一个好的工程结构能让你未来少踩很多坑。2.1 项目初始化与包管理使用 Vue 官方推荐的create-vue或直接使用 Vite 来初始化一个库模式的项目。# 使用 create-vue (推荐集成度更高) npm create vuelatest my-ui-library -- --typescript --vitest --eslint # 或使用 Vite 模板 npm create vitelatest my-ui-library -- --template vue-ts创建完成后你需要调整项目结构将其改造为“Monorepo”风格即使只有一个包这为未来扩展如分离文档站点、工具包留有余地。my-ui-library/ ├── packages/ # 核心包目录 │ └── core/ # 组件库核心包 │ ├── components/ # 组件源代码 │ ├── index.ts # 统一导出入口 │ └── package.json ├── docs/ # 文档站点项目可独立 ├── play/ # 开发调试 playground ├── package.json # 根目录 package.json (workspace配置) └── vite.config.ts # 构建配置在根目录package.json中配置workspaces以支持 Monorepo{ name: my-ui-library, private: true, version: 1.0.0, type: module, workspaces: [ packages/*, docs, play ], scripts: { dev: cd play npm run dev, build: cd packages/core npm run build, build:docs: cd docs npm run build } }2.2 构建配置打包出“对开发者友好”的产物这是核心环节。我们使用 Vite 来构建库。在packages/core/vite.config.ts中你需要进行针对性配置。// packages/core/vite.config.ts import { defineConfig } from vite import vue from vitejs/plugin-vue import { resolve } from path import dts from vite-plugin-dts // 用于生成 .d.ts 文件 export default defineConfig({ plugins: [ vue(), dts({ tsConfigFilePath: resolve(__dirname, tsconfig.json), outDir: resolve(__dirname, dist/types), // 类型文件输出目录 insertTypesEntry: true, // 生成 index.d.ts 入口 }), ], build: { lib: { entry: resolve(__dirname, index.ts), // 库的入口文件 name: MyUILibrary, // 全局变量名UMD格式用 fileName: (format) index.${format}.js, // 输出文件名 }, rollupOptions: { // 确保外部化处理那些你不想打包进库的依赖 external: [vue], output: { // 在 UMD 构建模式下为这些外部化的依赖提供一个全局变量 globals: { vue: Vue, }, // 提供更友好的代码分割和 Tree-shaking exports: named, }, }, // 输出目录 outDir: dist, // 清空输出目录 emptyOutDir: true, }, resolve: { alias: { : resolve(__dirname, src), }, }, })关键点解析build.lib指定库模式构建的入口和输出格式。external将vue外部化。这意味着使用你的库时需要用户自己安装 Vue而不是把你的库和 Vue 打包在一起。这能显著减小库的体积。vite-plugin-dts自动生成 TypeScript 类型声明文件这对使用者体验至关重要。输出格式Vite 默认会生成 ES 和 UMD 格式。ES 格式用于现代打包工具如 Vite、Webpack支持 Tree-shakingUMD 格式可用于直接浏览器script标签引入。2.3 样式方案选择与隔离样式处理是组件库的一大挑战。常见方案方案AScoped CSS 预处理器使用 Vue SFC 的style scoped。简单直接样式天然隔离但难以支持深度定制主题如换色。方案BCSS-in-JS (如 Vue 3.3 的useCssVars)动态性强主题切换容易但运行时性能有微损且样式无法被纯 CSS 项目复用。方案C独立 CSS 文件 BEM 命名规范将 CSS 输出为独立的.css文件。使用者可以覆盖也便于主题化。但需要严格的命名约定来避免冲突。方案DCSS 变量 静态提取利用 CSS 自定义属性定义设计 Token组件内部使用这些变量。通过构建工具将变量值静态化。这是目前主流 UI 库如 Element Plus采用的方案在可定制性和性能间取得了较好平衡。对于新手我建议从方案AScoped CSS开始快速验证组件功能。当需要主题定制时再逐步引入方案DCSS 变量。例如先定义一个tokens.css文件/* packages/core/src/styles/tokens.css */ :root { --my-primary-color: #409eff; --my-border-radius: 4px; --my-font-size-base: 14px; }然后在组件中使用!-- MyButton.vue -- template button classmy-button :class[type] slot / /button /template style scoped .my-button { background-color: var(--my-primary-color); border-radius: var(--my-border-radius); font-size: var(--my-font-size-base); } /style2.4 组件设计与开发Vue 3.4 的组合式 API 最佳实践Vue 3.4 对响应式性能做了优化并稳定了defineModel等语法糖。在开发组件时应充分利用组合式 API 的优势。一个标准的组件目录结构packages/core/src/components/MyButton/ ├── MyButton.vue # 组件主体 ├── index.ts # 组件导出文件 └── __tests__/ # 组件测试 └── MyButton.spec.tsMyButton.vue 示例script setup langts import { computed, withDefaults } from vue // 定义 Props interface Props { type?: primary | success | warning | danger size?: large | default | small disabled?: boolean loading?: boolean } // 使用 withDefaults 提供默认值 const props withDefaults(definePropsProps(), { type: primary, size: default, disabled: false, loading: false, }) // 定义 Emits const emit defineEmits{ click: [event: MouseEvent] }() // 使用 Computed 派生类名 const buttonClass computed(() [ my-button, my-button--${props.type}, my-button--${props.size}, { is-disabled: props.disabled, is-loading: props.loading, }, ]) // 点击事件处理 const handleClick (event: MouseEvent) { if (!props.disabled !props.loading) { emit(click, event) } } /script template button :classbuttonClass :disableddisabled || loading clickhandleClick span v-ifloading classloading-icon⏳/span slot / /button /template style scoped .my-button { /* ... 基础样式 ... */ } .my-button--primary { /* ... */ } .my-button.is-disabled { /* ... */ } /* ... 其他样式 ... */ /style关键实践使用script setup语法更简洁符合 Vue 3 潮流。严格定义 TypeScript 接口为 Props 和 Emits 提供类型这是组件库可靠性的基石。合理使用计算属性将模板中的复杂逻辑抽离保持模板清晰。提供灵活的插槽除了默认插槽考虑具名插槽如icon、suffix以满足扩展需求。2.5 统一导出与按需引入在packages/core/src/components目录下为每个组件建立一个index.ts文件// packages/core/src/components/MyButton/index.ts import MyButton from ./MyButton.vue export default MyButton export * from ./MyButton.vue // 可选导出类型然后在库的入口文件packages/core/index.ts中统一导出// packages/core/index.ts export { default as MyButton } from ./components/MyButton export { default as MyInput } from ./components/MyInput // ... 导出所有组件 // 可以导出一个 install 函数用于 Vue.use 全局安装 import type { App } from vue import * as components from ./components const install (app: App) { Object.entries(components).forEach(([key, component]) { app.component(key, component) }) } export default { install }为了实现类似import { MyButton } from my-ui-library的按需引入并支持 Tree-shaking你需要在package.json中正确设置入口{ name: my-org/ui-core, version: 0.1.0, main: ./dist/index.umd.js, module: ./dist/index.es.js, types: ./dist/types/index.d.ts, exports: { .: { import: ./dist/index.es.js, require: ./dist/index.umd.js, types: ./dist/types/index.d.ts }, ./style.css: ./dist/style.css }, files: [dist], peerDependencies: { vue: ^3.4.0 } }3. 配套让组件库真正“可用”的关键设施组件写完了怎么让别人包括你自己方便地用起来这需要一整套配套设施。3.1 文档与演示用 Vitepress 搭建你的“官网”文档是组件库的门面。Vitepress 基于 Vite 和 Vue与你的技术栈完美契合是构建文档站的不二之选。在docs目录初始化 Vitepress。为每个组件编写.md文档。文档应包括概述组件是做什么的。基础用法最简单的代码示例。APIProps、Events、Slots、Methods 的详细表格。更多示例展示不同属性组合的效果。集成实时演示Vitepress 支持在 Markdown 中直接编写 Vue 组件。你可以创建一个全局的演示包装器用于展示组件并显示对应代码。## MyButton 按钮 常用的操作按钮。 ### 基础用法 基础的按钮用法。 demo-container MyButton默认按钮/MyButton MyButton typeprimary主要按钮/MyButton MyButton typesuccess成功按钮/MyButton /demo-container vue template MyButton默认按钮/MyButton MyButton typeprimary主要按钮/MyButton MyButton typesuccess成功按钮/MyButton /template### 3.2 测试保障组件行为的稳定性 测试不是可选项而是生产级组件库的必需品。使用 Vitest与 Vite 生态兼容性好和 vue/test-utils。 **一个简单的组件测试示例** typescript // packages/core/src/components/MyButton/__tests__/MyButton.spec.ts import { describe, it, expect } from vitest import { mount } from vue/test-utils import MyButton from ../MyButton.vue describe(MyButton.vue, () { it(renders default slot content, () { const wrapper mount(MyButton, { slots: { default: Click Me, }, }) expect(wrapper.text()).toContain(Click Me) }) it(emits click event when clicked and not disabled, async () { const wrapper mount(MyButton) await wrapper.trigger(click) expect(wrapper.emitted()).toHaveProperty(click) }) it(does not emit click event when disabled, async () { const wrapper mount(MyButton, { props: { disabled: true, }, }) await wrapper.trigger(click) expect(wrapper.emitted(click)).toBeUndefined() }) })将测试脚本加入package.jsonscripts: { test: vitest run, test:watch: vitest, coverage: vitest run --coverage }3.3 版本、发布与 CI/CD走向自动化版本管理遵循语义化版本规范SemVer。major.minor.patch。patch修复 bug向后兼容。minor新增功能向后兼容。major破坏性变更。发布流程更新CHANGELOG.md记录本次变更。使用npm version [patch|minor|major]更新package.json中的版本号并打上 Git Tag。运行npm run build构建产物。运行npm publish --access public公共库或发布到私有仓库。CI/CD 集成在 GitHub Actions 或 GitLab CI 中配置自动化流程在推送代码到主分支或创建 Tag 时自动运行测试、构建并在测试通过后发布新版本。4. 演进从“能用”到“好用”的长期主义组件库不是一次性的项目而是一个需要持续维护和演进的产物。4.1 制定贡献规范当团队其他成员开始参与时需要明确的规范组件开发规范文件结构、命名规则、代码风格用 ESLint Prettier 固化。提交信息规范使用 Conventional Commits便于生成 ChangeLog。Pull Request 流程要求提供组件预览链接、测试覆盖、文档更新。4.2 建立反馈与迭代机制收集问题通过 GitHub Issues、内部讨论群或使用反馈组件。管理需求使用 Project 或 Milestone 来规划版本迭代。处理破坏性变更对于重大 API 变更提供迁移指南并考虑提供兼容层或同时维护两个大版本一段时间。4.3 性能与体积优化随着组件增多需要关注Tree-shaking确保你的库构建配置支持按需引入和 Tree-shaking。代码分割对于大型组件如富文本编辑器、图表考虑动态导入。样式优化检查并合并重复的 CSS 规则。使用v-memo在 Vue 3.4 中对渲染成本高、但依赖变化少的组件部分使用v-memo进行优化。4.4 向业务沉淀这是组件库价值最大化的阶段。定期复盘业务开发中的高频模式“我们为什么总是在不同的页面写类似的表单验证逻辑”“这个数据筛选条件组合在三个项目里出现了三次。”“所有项目的仪表盘都需要这个‘数据卡片’组件。”将这些模式抽象、标准化并沉淀为新的业务组件或Composables组合式函数。例如抽象出一个useFormValidation组合式函数或者一个StandardFilterPanel业务组件。这时你的组件库就从“UI 规范”升级为“业务解决方案仓库”这才是它不可替代的核心竞争力。回到开头的问题开发自己的 UI 组件库真正的终点不是复刻出另一个 Element而是在解决自身业务问题的过程中构建起一套可扩展、可维护、与业务共同成长的前端资产。它始于一个按钮但最终会成长为你团队研发效率与产品一致性的重要基石。Vue 3.4 提供了强大的技术底座而清晰的定位、扎实的工程化和持续的演进思维才是让这个基石稳固的关键。现在可以从一个Button和一份tokens.css开始迈出第一步了。