获课：shanxueit.com/12101/

从"重复造轮子"到"可持续迭代"：我用Vue3搭建组件库的几点个人思考

前言：为什么我们需要一个"自己的"组件库？

入行前端这些年，我经历过好几个项目从零到一的搭建过程。每个项目初期，团队都会面临一个灵魂拷问：是用现成的UI库（如Ant Design、Element Plus），还是自己搞一套？

用现成的，确实快，但遇到定制化需求时就各种别扭——要么改样式改得面目全非，要么为了一个交互细节不得不hack源码。自己搞呢，又怕投入产出比不划算，做着做着就成了一堆散装的"零件库"，毫无设计规范可言。

后来我慢慢想明白了一件事：团队真正需要的，不是一个"能用的组件集合"，而是一个"能跟着业务一起成长的组件生态系统"。 而Vue3带来的 Composition API、Teleport、Suspense 等新特性，恰好为我们搭建这样一个"可迭代"的组件库提供了绝佳的土壤。下面是我个人的一些实践体会和思考。

一、先想清楚"给谁用"，再动笔写代码

很多团队搭建组件库的第一个误区，就是一上来就开干，写着写着发现做了一堆没人用的组件。我的经验是：组件库的架构设计，80%的工作应该花在搞清楚"使用场景"上。

具体来说，我会把组件库的用户分成两类：

内部开发者——也就是你身边的同事。他们最在意的是：组件好不好用（API设计是否合理）、文档清不清晰（有没有示例代码）、出问题了怎么查（有没有调试手段）。对他们的需求，我的策略是"宁可少写一个组件，也要把每个组件的体验文档写透"。

外部消费者——如果是开源项目，还会有外部使用者。他们更在意：组件的稳定性（版本更新会不会 breaking change）、扩展性（能不能通过插槽或参数满足自己的定制需求）、性能表现（会不会拖慢页面）。

想清楚了这些，我才发现组件库的本质不是"技术项目"，而是一个"产品"。既然是产品，就得有版本规划、有迭代节奏、有用户反馈机制。这个认知转变，是我从"写组件"到"搭体系"的关键一步。

二、Vue3 的组合式 API，重新定义了"复用"的边界

说实话，Vue2 时代我是不太愿意写组件库的，因为 Options API 在封装复杂逻辑时总觉得有点"施展不开"——逻辑分散在 data、methods、computed 里，复用起来只能靠 mixins，而 mixins 的命名冲突和隐式依赖让人头大。

Vue3 的 Composition API 彻底改变了这件事。它让我可以把一个组件的"业务逻辑"从"渲染逻辑"中剥离出来。

什么意思呢？举个例子，一个下拉框组件，它的核心逻辑其实是"展开/收起"、"选项选择"、"键盘导航"这三件事。在 Vue3 里，我可以把这些逻辑封装成独立的 composable 函数（比如 useDropdown、useSelection、useKeyboardNavigation），然后在不同的组件里按需组合使用。

这样做的好处是什么？组件变成了"逻辑积木"的组装层，而不是"所有代码写在一起的大杂烩"。当业务需求变化时，我只需要调整 composable 的组合方式，而不需要重写整个组件。这种"逻辑层"和"视图层"的分离，是我认为 Vue3 在组件库工程化层面最大的贡献。

三、可迭代的基石：让"改组件"不再是一场噩梦

"可迭代"这三个字，说起来容易做起来难。我见过太多组件库，一开始设计得很完美，但业务需求一变，改一个组件的成本高得吓人。原因往往是：组件之间的耦合太紧，牵一发而动全身。

我自己的实践中，有两条原则帮了大忙：

原则一：组件分层，各司其职。

我把组件库分成三个层次：基础组件（按钮、输入框、图标）、复合组件（表格、表单、弹窗）、业务组件（用户选择器、商品卡片）。每一层只依赖下面一层，绝不跨层调用。这样一来，改基础组件时，只要保持API不变，上层组件完全不受影响。改动的"爆炸半径"被控制在了最小范围。

原则二：用"插槽"给用户留足退路。

一个组件库再强大，也不可能覆盖所有业务场景。与其把组件做得"大而全"，不如在关键位置留好插槽（slot），让使用者可以自由注入自己的模板。Vue3 的插槽机制比 Vue2 更灵活，特别是具名插槽和作用域插槽的组合使用，几乎可以应对任何定制化需求。当用户发现"这个组件不能满足我"的时候，插槽就是最后的救命稻草，而不需要他 fork 整个组件库去改源码。

四、工程化的"软实力"：文档、测试与发布

写组件只占了30%的工作量，剩下70%都在"让组件能被正确使用"这件事上。这是我做了两个组件库项目后最深刻的体会。

文档即入口。 一个组件库如果没有好用的文档，等于自断一臂。我比较推崇的方案是 VitePress + 组件源码驱动的文档生成——组件本身的 Props、Events、Slots 直接从 TypeScript 类型定义里提取，保证文档和代码永远同步。文档里还要有可交互的示例，让使用者可以直接在页面上改参数看效果。好的文档不是"说明书"，而是"试用间"。

测试保底线。 组件库的每一次发布，都应该有足够的信心说"这个版本不会搞崩现有项目"。这靠的不是人工回归测试，而是自动化测试。Vue3 生态里的 Vitest 和 Vue Test Utils 组合起来用，可以覆盖单元测试和组件渲染测试。我的习惯是：每个核心组件至少有一个"快照测试"，确保每次构建时渲染结果没有意外变化。

版本语义化。 可迭代意味着要不断发新版本，而发版本最怕的就是"改了一个小 bug，结果用户升级后整个页面白屏"。我严格遵循语义化版本规则：新增功能不破坏兼容性 -> 小版本号递增；修复 bug -> 补丁版本；有 breaking change -> 大版本升级。每次发版前，还要生成一个完整的 CHANGELOG，告诉用户"这次改了啥、影响有多大"。

五、实际效果与一点个人感悟

这套方法论在我最近维护的团队组件库上跑了一年多，数据还算能看：组件数量从最初的12个增长到47个，外部业务项目接入超过30个，版本从 v1.0.0 迭代到了 v2.3.1，期间经历了两次大版本升级，但接入项目升级的平均耗时从最初的"两天"缩短到了"两小时"。这就是"可迭代"体系的价值——不是不犯错，而是犯错之后修复和升级的成本可控。

说到底，搭建一个可迭代的 UI 组件库，技术选型只是表面，真正考验的是抽象能力和设计能力——你能不能看清业务背后的共性需求，把变化的部分和稳定的部分优雅地分离，让组件既能覆盖当下，又能包容未来。Vue3 给了我们足够趁手的工具，剩下的，就看我们如何用工程化的思维去用好它们了。

如果你也在做类似的事情，欢迎交流你的踩坑经验，前端这条路，大家一起走会更有意思。