组件库自动化最容易踩的几个坑组件库的问题常在发布之后才显现公共 UI 组件连接设计规范与业务代码。一个看似局部的属性调整可能影响多个调用方一个为了单页需求加入的样式入口也可能逐渐成为无法移除的公共 API。组件库自动化若只追求生成、构建和发包速度会把兼容性与维护成本留给下游。因此自动化要围绕可复查的边界组件职责是否清楚导出与副作用是否符合打包约定设计令牌是否被正确使用公共类型变化能否提前发现。下面几类问题不能靠一条通用规则解决但都可以在评审与流水线中较早暴露。容易积累维护成本的做法1. “上帝组件”陷阱The God Component Anti-Pattern设计者不断给Table或Modal增加布尔开关和业务属性久而久之同一组件承担数据获取、状态、布局与业务流程。Props 数量和文件行数只能提示问题真正要看的是这些选项是否可以独立组合、是否有相互排斥的状态以及修改一项是否需要理解全部分支。2. 破坏 Tree-Shaking 的全量导出export *本身不必然阻止 Tree-Shaking结果还受模块格式、包的副作用声明和使用方构建器影响。需要检查的是入口模块是否在导入时执行注册、加载样式或聚合无法静态分析的代码。组件库应输出可分析的 ESM并用实际消费项目验证按需引入结果不能只凭导出语法推断体积。3. Design Token 语义断层与硬编码样式设计团队定义了 Token组件内部却继续写入颜色和间距字面量主题切换时就难以统一调整。但不是所有数值都必须成为公共 Token几何计算或仅属于组件内部的不变量可以保留。规则应区分语义样式与实现细节并允许有说明的例外。4. 缺乏 Breaking Change破坏性变更自动化检测TypeScript 声明变化可以在 CI 中比较但类型兼容也不是全部。默认值、事件顺序、DOM 结构和 CSS 选择器变化都可能影响调用方。自动检查负责列出候选破坏项版本决策仍需结合迁移说明与消费方测试。把自动化放在明确契约上复合组件适合表达可组合的层次关系但简单组件不必为了模式而拆分。选择 API 形式时先列出稳定职责和需要共同维护的状态。无法独立组合的选项保留在一个接口里可能更清楚业务流程则不应被塞进基础组件。sideEffects要与包的真实行为一致。若组件导入会注册全局内容或加载 CSS错误标成无副作用可能让构建器删掉必要代码。建立一个最小消费应用分别导入单个组件与完整入口检查最终产物和样式比只看 package.json 更可靠。公共.d.ts可以在每次变更后生成并比较。工具指出删除导出、收紧属性或新增必填项再由维护者决定这是缺陷、需要主版本发布的变更还是检测器误报。门禁应输出具体符号与差异不用一个笼统分数代替评审。一个 TypeScript 声明比较示例下面的ComponentApiLinter演示如何读取两个声明文件并查找导出或属性变化。它不是完整的兼容性判断示例没有覆盖函数参数、联合类型、泛型、别名解析也没有识别“新版本新增必填属性而旧版不存在”的情况。接入 CI 前需要补齐项目关心的符号并用已知兼容与不兼容样本验证。import * as ts from typescript; import * as fs from fs; export interface ApiChangeResult { hasBreakingChange: boolean; messages: string[]; } /** * 组件库 API 破坏性变更 Lint 检测器 */ export class ComponentApiLinter { /** * 比较旧版与新版 .d.ts 导出的接口定义 * param oldDtsPath 旧版本 d.ts 声明文件路径 * param newDtsPath 新版本 d.ts 声明文件路径 */ public static compareDts(oldDtsPath: string, newDtsPath: string): ApiChangeResult { const oldExports this.extractExportedTypes(oldDtsPath); const newExports this.extractExportedTypes(newDtsPath); const messages: string[] []; let hasBreakingChange false; // 1. 检查是否存在被删卸的导出组件或接口 for (const [name, oldType] of oldExports.entries()) { if (!newExports.has(name)) { hasBreakingChange true; messages.push(❌ Breaking Change: 导出的类型/组件 ${name} 被直接删除); continue; } const newType newExports.get(name)!; // 2. 如果是接口 (Interface / Type Props)检查必填属性是否增加 for (const [propName, isRequired] of oldType.properties.entries()) { if (!newType.properties.has(propName)) { hasBreakingChange true; messages.push(❌ Breaking Change: 组件 ${name} 的属性 ${propName} 被移除); } } for (const [propName, isRequired] of newType.properties.entries()) { const oldPropRequired oldType.properties.get(propName); // 如果旧属性原本不是必填新版本强行改成了必填 (Required)视为破坏性改动 if (oldPropRequired false isRequired true) { hasBreakingChange true; messages.push(❌ Breaking Change: 组件 ${name} 的属性 ${propName} 从可选变为了强必填); } } } return { hasBreakingChange, messages }; } /** * 使用 TS Compiler API 提取文件的导出 Symbol 类型 */ private static extractExportedTypes(filePath: string): Mapstring, { properties: Mapstring, boolean } { const program ts.createProgram([filePath], { target: ts.ScriptTarget.ESNext }); const checker program.getTypeChecker(); const sourceFile program.getSourceFile(filePath); const result new Mapstring, { properties: Mapstring, boolean }(); if (!sourceFile) return result; const moduleSymbol checker.getSymbolAtLocation(sourceFile); if (moduleSymbol) { const exports checker.getExportsOfModule(moduleSymbol); for (const exp of exports) { const name exp.getName(); const properties new Mapstring, boolean(); const type checker.getTypeOfSymbolAtLocation(exp, exp.valueDeclaration || exp.declarations![0]); const props type.getProperties(); for (const p of props) { const propName p.getName(); // 判断该属性是否是可选的 (Optional) const isOptional (p.flags ts.SymbolFlags.Optional) ! 0; properties.set(propName, !isOptional); } result.set(name, { properties }); } } return result; } } // CI/CD 质量检测示例 if (require.main module) { const oldDts ./dist/old/index.d.ts; const newDts ./dist/new/index.d.ts; if (fs.existsSync(oldDts) fs.existsSync(newDts)) { const result ComponentApiLinter.compareDts(oldDts, newDts); if (result.hasBreakingChange) { console.error( CI 打回: 组件库检测到破坏性 API 变更); result.messages.forEach(msg console.error(msg)); process.exit(1); } else { console.log(✅ API 兼容性检测通过未发现 Breaking Change); } } }评审时可以怎样落地评估维度常见反模式 (Bad Practice)可复查的改进方式组件 API 设计业务选项不断进入基础组件状态组合难以说明根据职责选择复合组件、受控属性或业务包装层样式覆盖机制任意覆盖内部结构升级时无法判断影响提供语义 Token 和有限扩展点例外由评审确认构建导出格式入口含隐式副作用按需引入结果不可预测提供可分析模块并用最小消费应用验证产物版本变更管理只靠肉眼查看公共类型生成声明差异再补充行为测试和迁移说明发布前还要验证消费方组件库自身测试通过后选择代表性的消费项目安装候选版本运行类型检查、构建和关键交互。CSS、运行时依赖与框架版本问题往往只有在消费端出现。测试使用公开示例或虚构页面不复制业务系统的敏感内容。发布记录应关联声明差异、产物信息、变更说明和迁移办法。发现破坏项时不要为了保持小版本号而隐藏它决定撤回时也要确认包仓库、锁文件和缓存中的版本状态。组件库自动化的价值是让变化较早被看见并能被复验而不是让发包动作本身更快。