组件库日常巡检的关键检查项组件库的问题很少只停留在组件库里。一个属性类型变化、全局样式泄漏或错误的导出方式都会传到许多业务应用。日常巡检的价值是在发布前发现这些影响并告诉维护者具体变了什么而不是等业务团队升级后再从页面异常倒查。巡检项不宜一味增加。公共 API、交互行为、视觉结果、构建产物和发布信息是几条不同证据链应分别给出结果。每条检查还要有负责人和处理方式哪些变化必须阻断哪些需要人工确认哪些只作为趋势记录。公共 API 先与上一版基线比较组件的 props、导出名称和类型声明属于使用方可以依赖的接口。删除导出、把可选属性改为必填、缩小联合类型通常都需要明确的迁移安排。仅靠搜索Props接口不够因为类型可能通过别名、交叉类型、泛型或再导出暴露多个组件也可能有同名属性。更稳妥的方式是从真实入口生成声明文件或 API 报告再与上一版已发布基线比较。差异由维护者确认新增兼容能力可以接受弃用项要保留说明破坏性变化则匹配相应版本和迁移文档。工具负责找差异是否破坏兼容仍需要结合类型语义判断。巡检还应放一个最小消费者项目。它只从包的公开入口导入常用组件完成类型检查和构建。这样能发现声明文件虽然生成成功实际exports、路径或模块格式却无法被使用的问题。消费者项目不要引用组件库源码否则会绕过真正的发布边界。行为测试比快照更接近用户按钮能不能获得焦点弹窗能否用键盘关闭表单错误是否与输入关联这些行为无法由像素截图充分证明。基础组件应优先保留面向角色和可访问名称的交互测试再使用视觉回归捕捉布局、颜色和间距变化。弹窗、下拉框和浮层要覆盖打开、关闭、焦点返回、滚动和叠层。异步组件则测试加载、空数据、错误和取消。测试不必枚举所有业务组合但需要覆盖组件承诺支持的状态。发现问题时报告应指出具体 Story、操作和断言不能只给一张失败截图。视觉回归需要稳定环境截图差异会受浏览器版本、字体、动画、时区和数据变化影响。基线应在固定浏览器和字体环境中生成Story 使用静态数据隐藏当前时间与随机内容。阈值根据组件特点确定不要复制一个极小比例后把所有差异都当噪声也不要设置得过宽而漏掉真正变化。下面的 Playwright 示例固定视口、等待字体并关闭动画。componentsToTest应来自维护过的 Story 清单新增公共组件时同步补充而不是假定自动遍历出的每个 Story 都适合截图。import { test, expect } from playwright/test; const componentsToTest [ { name: Button Primary, storyId: components-button--primary }, { name: Modal Danger, storyId: components-modal--danger }, { name: Table Empty, storyId: components-table--empty }, ]; test.describe(component visual regression, () { for (const { name, storyId } of componentsToTest) { test(name, async ({ page }) { await page.setViewportSize({ width: 1024, height: 768 }); await page.goto(/iframe.html?id${storyId}viewModestory); await page.locator(#storybook-root).waitFor(); await page.evaluate(() document.fonts.ready); await expect(page.locator(#storybook-root)).toHaveScreenshot( ${storyId}.png, { animations: disabled }, ); }); } });差异出现后先看原因再决定更新基线。预期中的设计调整需要附上变更说明和评审记录字体没加载、动画未停或测试数据变化则修复测试环境。直接批量接受新截图会让视觉回归失去意义。构建产物要用实际导入方式验证包体积巡检不能只看组件库输出目录总大小。业务应用可能只导入一个 Button却因为入口副作用、聚合导出或打包配置把整库带入。准备一个小型消费者构建分别测试常见按需导入方式再查看产物中实际包含的模块会比单纯压缩文件大小更可靠。体积预算应基于当前基线和使用场景。超出预算先列出新增依赖、重复版本和不可摇除模块不必立即把一次合理增长判为错误。若变化来自新能力维护者可以评估拆分入口若是不小心全量导入图标或语言包报告应给出依赖路径。sideEffects声明也要与真实代码一致。包含全局 CSS、注册逻辑或 polyfill 的文件不能为了 Tree-Shaking 随意标为无副作用。更好的做法是把全局入口与纯组件入口分开让使用方显式选择。样式边界需要专门巡检组件库应避免无意修改body、通用标签和业务类名。基础 Reset 如果是产品约定就作为单独入口提供并写明作用范围不要随某个组件导入。CSS Modules、CSS-in-JS 或命名前缀能减少冲突但仍要检查 Portal、全局变量和第三方样式的实际输出。可以在一个带有故意冲突样式的宿主页中渲染组件观察双方是否互相覆盖。主题变量则测试默认值、局部覆盖和缺失值。暗色主题或高对比模式若是公开能力也应放入行为与视觉用例而不是只在文档示例里出现。巡检结果要进入发布决策每次发布前汇总 API 差异、行为测试、视觉变更、消费者构建和体积变化。报告链接到具体产物并标明阻断项、待确认项和已知限制。弃用 API 要给迁移办法和预计移除版本不能只在类型上加一行注释。不是所有检查都需要放在本地 Git 钩子里。快速的类型与单元测试适合开发阶段运行完整浏览器矩阵和消费者构建可以交给 CI。把昂贵任务塞进每次推送往往只会促使开发者绕过检查。日常巡检最终要回答一个简单问题这次发布会让现有使用方看到哪些变化他们如何验证和回退。能持续回答这个问题组件库才能在频繁迭代时保持可预测而不是靠维护者记住所有潜在影响。
组件库日常巡检的关键检查项
组件库日常巡检的关键检查项组件库的问题很少只停留在组件库里。一个属性类型变化、全局样式泄漏或错误的导出方式都会传到许多业务应用。日常巡检的价值是在发布前发现这些影响并告诉维护者具体变了什么而不是等业务团队升级后再从页面异常倒查。巡检项不宜一味增加。公共 API、交互行为、视觉结果、构建产物和发布信息是几条不同证据链应分别给出结果。每条检查还要有负责人和处理方式哪些变化必须阻断哪些需要人工确认哪些只作为趋势记录。公共 API 先与上一版基线比较组件的 props、导出名称和类型声明属于使用方可以依赖的接口。删除导出、把可选属性改为必填、缩小联合类型通常都需要明确的迁移安排。仅靠搜索Props接口不够因为类型可能通过别名、交叉类型、泛型或再导出暴露多个组件也可能有同名属性。更稳妥的方式是从真实入口生成声明文件或 API 报告再与上一版已发布基线比较。差异由维护者确认新增兼容能力可以接受弃用项要保留说明破坏性变化则匹配相应版本和迁移文档。工具负责找差异是否破坏兼容仍需要结合类型语义判断。巡检还应放一个最小消费者项目。它只从包的公开入口导入常用组件完成类型检查和构建。这样能发现声明文件虽然生成成功实际exports、路径或模块格式却无法被使用的问题。消费者项目不要引用组件库源码否则会绕过真正的发布边界。行为测试比快照更接近用户按钮能不能获得焦点弹窗能否用键盘关闭表单错误是否与输入关联这些行为无法由像素截图充分证明。基础组件应优先保留面向角色和可访问名称的交互测试再使用视觉回归捕捉布局、颜色和间距变化。弹窗、下拉框和浮层要覆盖打开、关闭、焦点返回、滚动和叠层。异步组件则测试加载、空数据、错误和取消。测试不必枚举所有业务组合但需要覆盖组件承诺支持的状态。发现问题时报告应指出具体 Story、操作和断言不能只给一张失败截图。视觉回归需要稳定环境截图差异会受浏览器版本、字体、动画、时区和数据变化影响。基线应在固定浏览器和字体环境中生成Story 使用静态数据隐藏当前时间与随机内容。阈值根据组件特点确定不要复制一个极小比例后把所有差异都当噪声也不要设置得过宽而漏掉真正变化。下面的 Playwright 示例固定视口、等待字体并关闭动画。componentsToTest应来自维护过的 Story 清单新增公共组件时同步补充而不是假定自动遍历出的每个 Story 都适合截图。import { test, expect } from playwright/test; const componentsToTest [ { name: Button Primary, storyId: components-button--primary }, { name: Modal Danger, storyId: components-modal--danger }, { name: Table Empty, storyId: components-table--empty }, ]; test.describe(component visual regression, () { for (const { name, storyId } of componentsToTest) { test(name, async ({ page }) { await page.setViewportSize({ width: 1024, height: 768 }); await page.goto(/iframe.html?id${storyId}viewModestory); await page.locator(#storybook-root).waitFor(); await page.evaluate(() document.fonts.ready); await expect(page.locator(#storybook-root)).toHaveScreenshot( ${storyId}.png, { animations: disabled }, ); }); } });差异出现后先看原因再决定更新基线。预期中的设计调整需要附上变更说明和评审记录字体没加载、动画未停或测试数据变化则修复测试环境。直接批量接受新截图会让视觉回归失去意义。构建产物要用实际导入方式验证包体积巡检不能只看组件库输出目录总大小。业务应用可能只导入一个 Button却因为入口副作用、聚合导出或打包配置把整库带入。准备一个小型消费者构建分别测试常见按需导入方式再查看产物中实际包含的模块会比单纯压缩文件大小更可靠。体积预算应基于当前基线和使用场景。超出预算先列出新增依赖、重复版本和不可摇除模块不必立即把一次合理增长判为错误。若变化来自新能力维护者可以评估拆分入口若是不小心全量导入图标或语言包报告应给出依赖路径。sideEffects声明也要与真实代码一致。包含全局 CSS、注册逻辑或 polyfill 的文件不能为了 Tree-Shaking 随意标为无副作用。更好的做法是把全局入口与纯组件入口分开让使用方显式选择。样式边界需要专门巡检组件库应避免无意修改body、通用标签和业务类名。基础 Reset 如果是产品约定就作为单独入口提供并写明作用范围不要随某个组件导入。CSS Modules、CSS-in-JS 或命名前缀能减少冲突但仍要检查 Portal、全局变量和第三方样式的实际输出。可以在一个带有故意冲突样式的宿主页中渲染组件观察双方是否互相覆盖。主题变量则测试默认值、局部覆盖和缺失值。暗色主题或高对比模式若是公开能力也应放入行为与视觉用例而不是只在文档示例里出现。巡检结果要进入发布决策每次发布前汇总 API 差异、行为测试、视觉变更、消费者构建和体积变化。报告链接到具体产物并标明阻断项、待确认项和已知限制。弃用 API 要给迁移办法和预计移除版本不能只在类型上加一行注释。不是所有检查都需要放在本地 Git 钩子里。快速的类型与单元测试适合开发阶段运行完整浏览器矩阵和消费者构建可以交给 CI。把昂贵任务塞进每次推送往往只会促使开发者绕过检查。日常巡检最终要回答一个简单问题这次发布会让现有使用方看到哪些变化他们如何验证和回退。能持续回答这个问题组件库才能在频繁迭代时保持可预测而不是靠维护者记住所有潜在影响。
