Chromatic 按快照计费账单上涨通常不是代码写多了而是快照策略太松。Storybook 全量出图、多 viewport、多主题、每次 push 都跑完整流水线几项叠加月账单很快就上去了。其实大多数组件库根本不需要“每次全量截图”把无效快照删掉、把触发范围收窄成本可以显著下降。这次我们从一个组件库项目的实际优化过程出发分享一套适用于 Chromatic、Percy、Lost Pixel 以及 Playwright 自建基线的通用降本方案。核心思路归纳成一句话把“视觉回归”的限制条件从“能截就截”改成“必须截才截”。文章会讲清楚成本模型、三层优化手段、CI 配置、验证方法和常见坑位让你在现有工具上直接落地不需要换平台。1. 视觉测试成本模型先把钱花在哪里搞清楚视觉测试工具的计费单位通常不是“构建次数”而是Snapshot快照。Chromatic 的套餐和超额计费围绕快照数量展开Percy 的按量逻辑也类似。一次快照是一次完整的截图 基线对比会占用额度、产生存储、参与构建记录。所以成本优化的本质是减少快照总数。一个组件库项目的月度快照消耗可以用下面这个公式估算月度快照总量 ≈ Story 总数 × 单个 Story 平均视口变体数 × 平均模式变体数 × CI 运行次数四个变量里任何一个放大成本都会成倍上涨。很多团队遇到的情况是“四个变量一起涨”Story 数量随组件库膨胀从 200 涨到 1000Storybook 配置了 3 个 viewport组件支持 light / dark 两套主题CI 里每次 push 都全量跑一次 Chromatic。结果就是一个 Story 可能产出 6 张快照1000 个 Story 一轮就跑 6000 张快照。如果团队一天合入 10 个 PR一个月轻松突破十万甚至几十万快照。账单高不是因为工具贵而是因为策略默认全量。所以在动手优化前建议先建一个成本基线登录 Chromatic / Percy 控制台找到最近 30 天的快照用量数据。统计当前 Storybook 里有多少个 stories。统计 CI 中视觉测试任务每天跑多少次。把四个变量填入公式算出当前理论快照量。有了基线后续每做一次优化都可以对比快照数的变化而不是凭感觉判断效果。成本变量现状优化方向Story 总数可能上千删除调试、重复、文档型 stories视口变体数每个 story 3-5 个收敛到 2-3 个真实断点主题/模式变体数每 story 2-4 个只对受影响组件保留多模式CI 运行次数每次 push 全量跑turboSnap 增量 触发条件裁剪2. 第一层优化删除没有价值的快照最快见效的动作是给“不需要视觉回归”的 stories 关闭快照。这个问题在大型组件库里非常普遍为了 Storybook 文档足够完整团队会写很多演示型 stories但其中相当一部分没有像素级对比的价值。举例来说下面几类 story 应该优先关掉视觉快照纯文案展示页例如“颜色变量总览”“字体样式表”内容改一次就要重新出图但几乎没有回归风险。Debug 用的临时 story比如_Playground、AllComponents、EverythingInOnePage。带随机数据、时间戳、实时状态的用例每次截图结果都可能不同基线永远不稳定。只用于文档渲染不用于交互测试的装饰性组件。依赖后端数据且没有 Mock 的页面截图结果不可控。在 Storybook CSF 3.0 写法下关闭单个 story 的快照非常直接// Button.stories.tsx import type { Meta, StoryObj } from storybook/react; import { Button } from ./Button; const meta { title: Components/Button, component: Button, } satisfies Metatypeof Button; export default meta; type Story StoryObjtypeof meta; export const Primary: Story { args: { variant: primary, children: 保存, }, }; export const LoadingDemo: Story { args: { loading: true, children: 加载中, }, parameters: { chromatic: { disableSnapshot: true }, }, };如果想对整个模块关闭可以在该 stories 文件的meta里配置const meta { title: Marketing/AnimationHero, component: AnimationHero, parameters: { chromatic: { disableSnapshot: true }, }, } satisfies Metatypeof AnimationHero;这种方式不会从 Storybook 文档中移除 story只是不让 Chromatic 对它截图。使用 Chromatic 时建议在项目里建立明确约定凡是带deprecated标记、纯展示型、或明确不需要视觉回归的 story都要带disableSnapshot。这一步通常能直接砍掉 20%-40% 的快照量。3. 第二层优化收敛 viewport、主题和浏览器变体删除快照只是第一步更精细的操作是控制单个 story 的变体数。Storybook 默认只截一个桌面宽度但如果你的项目配置了storybook/addon-viewport并且 Chromatic 在默认情况下会读取 story 的viewport参数那多个宽度就会产生多张快照。主题同理只要组件存在 light / dark 两套模式一个 story 就会变成两张图。很多团队的误区是给所有 story 配置了 4-5 个 viewport理由是“要保证移动端适配”。但实际业务中真正需要肉眼检查的宽度只有几个关键断点。推荐的做法是按项目实际断点收敛390 宽度覆盖主流手机768 宽度覆盖平板或小屏笔记本1280 / 1440 宽度覆盖桌面端并非每个组件都需要三个 width。按钮、图标、颜色徽标这类基础组件一个桌面宽度就够。有布局需求的组件才需要移动端宽度。// Card.stories.tsx export const WithMobileLayout: Story { parameters: { chromatic: { viewports: [390, 1440], }, }, };如果组件库使用主题系统建议只对受主题影响明显的组件开启多模式。一个 Button 通常不需要在 4 套主题下各截图一张而一个带有大面积背景和文字颜色的 PageHeader则值得在 light / dark 下各拍一张。// PageHeader.stories.tsx export const Light: Story { parameters: { chromatic: { modes: { light: { theme: light }, dark: { theme: dark }, }, }, }, };还要注意浏览器矩阵。Chromatic 默认会对项目配置的浏览器组合生成快照。对绝大部分组件库来说Chromium 覆盖已经足够。只有在处理-webkit-私有样式、复杂字体渲染、特殊 canvas 绘制时再考虑增加 WebKit / Firefox。浏览器变量是成本放大器建议默认只保留一个核心浏览器按需添加。4. 第三层优化turboSnap 增量和 CI 触发裁剪完成变体收敛后下一个重点是“触发频率”。一个组件库哪怕只有 300 个 story如果每提交一次就跑全套一个月下来依然很可观。Chromatic 的 turboSnap 正是解决这个问题的。turboSnap 的核心逻辑读取 Git 变更信息分析本次提交涉及哪些源码文件再通过构建依赖图找出受影响的上游 stories只对这部分重新截图。没有变化的组件不会重新出图。启用方式是在 Chromatic CLI 命令中加上--only-changednpx chromatic \ --project-token你的项目令牌 \ --only-changed这个参数需要结合 CI 使用有两个容易被忽略的前提。第一Checkout 必须拿到完整 Git 历史。默认的 GitHub Actions checkout 如果是浅克隆turboSnap 可能拿不到足够信息结果变成“每次都没有命中”最后还是全量跑。所以 CI 中要设置fetch-depth: 0。第二如果项目使用 monorepo 或 pnpm workspace需要确认构建工具链能被正确解析。遇到“明明改动一个组件却重新截图了一堆无关页面”的情况优先查依赖图和构建配置。CI 配置示例name: visual-test on: pull_request: types: [opened, synchronize] jobs: chromatic: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 with: fetch-depth: 0 - uses: actions/setup-nodev4 with: node-version: 20 - run: npm ci - run: npm run build:storybook - run: npx chromatic --only-changed --exit-zero-on-changes这里--exit-zero-on-changes的作用是让视觉变更不直接阻断 CI而是作为人工审查结果避免“每次截图 diff 都让流水线失败团队被迫全部通过”的坏习惯。是否启用取决于团队的检查流程。除了 turboSnap还可以在 CI 层面对提交信息做筛选。比如只对真实源码变更的提交跑视觉测试对文档、依赖、样式命名这类提交直接跳过npx chromatic --only-changed --skip docs|chore|deps|style:需要注意--skip只适合跳过后端提交信息明确不涉及视觉代码的 PR不能作为默认规则。如果团队习惯把代码和文档混在一个 commit 里跳过策略反而会导致漏检。5. 把不需要截图的用例踢出视觉测试工具视觉回归工具适合解决“像素级变化是否可接受”的问题但它不是唯一的质量手段。很多场景其实可以用单元测试或纯交互测试替代。典型的例子包括日期选择器的日期计算逻辑应该用 Jest 断言日期输出而不是等 Chromatic 截图下去对比。表单校验错误文本可以用 Testing Library 断言文案出现不依赖截图。无头浏览器中的点击、输入、键盘导航用 Playwright 断言 DOM 状态即可不需要生成基线图。组件 API 输出结果属于单元测试职责。如果一个用例的“变化”不影响渲染结果或者能通过 DOM 断言精确定位就不要让它进入视觉测试链路。这样不仅省钱还能减少基线更新频率。甚至可以只把“真正的像素布局”留给视觉快照// 交互逻辑走 DOM 断言不走截图 import { test, expect } from playwright/test; test(日期选择器选择后输出指定格式, async ({ page }) { await page.goto(/iframe.html?iddate-picker--defaultviewModestory); const input page.getByRole(textbox, { name: /日期/ }); await input.fill(2025-04-01); await expect(page.locator(.selected-value)).toHaveText(2025-04-01); });这类测试占用的 CI 时间更短又没有快照额度消耗适合高频执行。视觉测试只保留那些“必须通过图片对比才能判断”的用例。6. 如果还想更省自建 Playwright 基线对比当快照量压缩到一定程度后还可以考虑把一部分低频组件从 Chromatic / Percy 迁到自建基线。Playwright 官方提供了toHaveScreenshot完全可以在本地 CI 里做视觉回归。思路不复杂构建 Storybook 静态站点。在本地启动静态服务。Playwright 打开iframe.html?idstoryIdviewModestory。调用toHaveScreenshot生成或对比基线。把基线截图提交到 Git 或对象存储。一个简化示例// e2e/visual.spec.ts import { test, expect } from playwright/test; const STORYBOOK_URL http://127.0.0.1:6006; test(Button Primary 视觉回归, async ({ page }) { await page.setViewportSize({ width: 1440, height: 900 }); await page.goto( ${STORYBOOK_URL}/iframe.html?idcomponents-button--primaryviewModestory ); const root page.locator(#storybook-root); await expect(root).toHaveScreenshot(button-primary.png, { maxDiffPixelRatio: 0.03, }); });使用 Playwright 自建基线有几个坎要注意首次运行需要生成基线图作为--update-snapshots提交进仓库。字体加载、图片加载会影响截图稳定性需要显式等待资源加载完成。CI 中需要固定浏览器版本避免 Playwright 自动升级后截图出现系统性差异。基线图会占仓库体积建议对快照目录做.gitattributes或 LFS 配置。自建方案不产生按快照计费的成本但需要团队自己维护基线、构建服务、静态资源和失败处理。比较稳妥的迁移路径是先把低风险、低变更频率的基础组件迁过去核心业务页面继续留在 Chromatic / Percy 做最终人工验收形成“混合模式”。7. 优化后效果验证怎么确认没有漏检成本降下来之后要回答一个关键问题视觉回归的质量有没有下降光看快照数量减少还不够必须让团队确认“真正重要的页面仍然在对比”。推荐建立一套效果验证清单每次优化后执行一次在测试环境故意修改某个核心组件的颜色确认视觉任务失败。故意修改一个无关组件确认 turboSnap 没有触发全量截图。检查 Chromatic 的构建报告确认当天 snapshot 数量明显减少。抽查 10 个关闭快照的 story确认它们确实不需要视觉对比。确认核心用户路径比如首页、登录页、结算页仍然有基线快照。另外需要注意稳定性问题。如果视觉测试频繁因为动画、字体加载、网络请求而出现“假 diff”团队就会开始批量接受变更基线失去意义。可以从三个方向处理在 story 的parameters.chromatic.delay中增加等待时间。在 Storybook 预览中禁用 CSS 动画。对包含异步请求的组件使用固定 Mock 数据避免返回结果变化。优化不是简单把全部 story 的disableSnapshot打开而是让剩余的快照更稳定、更有代表性。8. 用脚本批量统计和管理快照当组件库规模较大时人工核对 stories 是否开启快照并不现实。建议在项目中加入一个成本估算脚本扫描所有 stories 文件粗算出当前理论快照量方便后续每次改动都能对比。// scripts/estimate-snapshots.mjs import { glob } from glob; import fs from node:fs; function estimateSnapshotCount(baseDir src) { const files glob.sync(${baseDir}/**/*.stories.(ts|tsx|js|jsx), { ignore: **/node_modules/** }); let total 0; let storyCount 0; for (const file of files) { const content fs.readFileSync(file, utf8); // 粗统计每个 export const 算一个 story const stories (content.match(/export const \w/g) || []).length; const viewports (content.match(/viewports:/g) || []).length; const hasModes /modes:/.test(content); const viewportCount viewports 0 ? viewports : 1; const modeCount hasModes ? 2 : 1; const disabled /disableSnapshot/.test(content); if (!disabled) { storyCount stories; total stories * viewportCount * modeCount; } } console.log(story count:, storyCount); console.log(estimated snapshots per run:, total); } estimateSnapshotCount();这个脚本属于“粗算”工具最终计费以平台后台数据为准但用来观察优化趋势已经足够。如果团队使用 Chromatic CLI可以在 CI 完成后把构建信息输出到日志再把日志汇总到监控系统。很多管理后台支持 GraphQL 或 REST 接口拉取构建列表但具体字段不同。建议从官方文档确认不要针对某个内部接口写死解析逻辑。批量任务层面可以采用“PR 增量 定时全量”的组合name: visual-test-full on: schedule: - cron: 0 2 * * 1 jobs: chromatic: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 with: fetch-depth: 0 - run: npm ci - run: npm run build:storybook - run: npx chromatic --project-token${{ secrets.CHROMATIC_PROJECT_TOKEN }}PR 触发时用--only-changed做增量每周一次定时任务跑全量检查整个组件库的视觉状态。这样既控制了日常成本又保留了周期性的完整覆盖。9. 资源占用与 CI 性能观察快照量下降后CI 视觉测试的时间通常也会同步下降。观察性能时重点看这几个指标指标观察方式优化后的预期视觉测试任务总耗时CI 页面中 job 耗时增量模式下明显缩短单次构建上传快照数Chromatic 构建报告从全量降为受影响 stories 数量Storybook 构建时间CI 日志影响不大主要是静态构建耗时基线图仓库体积Git 仓库大小移除无效快照后增长放缓控制台超量提示平台账单页不再频繁触发超额提醒如果发现--only-changed开启后任务耗时并没有下降优先排查 Git 历史是否完整、构建配置是否正确读取依赖图。monorepo 项目中跨包依赖未正确声明会导致 turboSnap 把所有包都标记为受影响这时需要检查chromatic.config的项目根目录配置。10. 常见问题与排查方法问题现象可能原因排查方式解决方案开启--only-changed后仍然全量截图CI 浅克隆缺少 Git 历史检查 checkout 步骤日志设置fetch-depth: 0某个组件截图反复 diff动画、字体加载、异步数据不稳定查看 diff 图和截图时间增加delay、禁用动画、固定 Mock 数据配置disableSnapshot后不再出图参数位置写错或版本不兼容检查 Storybook 参数类型按当前版本文档确认参数层级快照量下降但账单没下降平台套餐周期未到查看账单周期边界等周期结束后再对比viewport 配置没有生效Storybook 版本与 Chromatic 版本不匹配检查浏览器控制台警告升级或锁定兼容版本跳过太多生产环境出现回归--skip规则过宽检查跳过规则与提交信息收窄跳过范围仅用于明确无视觉改动自建 Playwright 快照在 CI 不一致浏览器版本或系统字体差异对比本地与 CI 截图固定 Docker 镜像和 Playwright 浏览器版本11. 视觉测试降本最佳实践把整套方案落地时建议按下面的顺序执行避免一次性改太多导致团队失去信心先花半天拉取当前快照量和成本基线。建立“story 是否需要视觉快照”的评审规则统一在组件库文档中标注。先删除明显无价值的 stories 快照看一周效果。收敛全局 viewport 和主题模式优先保留核心断点。开启 turboSnap并验证增量命中。用 Playwright 交互断言替代部分非像素型用例。把核心页面和关键组件留在托管平台低风险组件逐步迁到自建基线。每周固定时间检查一次快照统计和 CI 耗时发现反弹及时调整。合规方面也要做几个收口视觉测试账号使用脱敏后的测试数据不要在截图里暴露真实用户、手机号、邮箱等个人信息。如果测试环境接入第三方系统确保数据来源合法避免把生产数据直接带到视觉测试平台。外部平台的项目令牌统一放入 CI 的 Secrets不要写进代码仓库。涉及用户肖像、版权素材的页面不要提交到公网可访问的视觉测试项目。这些边界不只是成本问题也关系到测试数据保护和团队安全习惯。12. 总结与下一步这次我们拆解的其实不是“怎样少付钱”而是“怎样让视觉回归只在必要的时候产生必要的结果”。删除无效快照、收敛 viewport 和主题、开启增量模式、把非视觉用例移到其他测试层四步做到位快照量通常能降到原来的十分之一左右。这个结论在 Chromatic 上成立在 Percy、Lost Pixel、Playwright 自建基线上同样成立。最值得先验证的是 turboSnap 的命中效果打开一个改动最小的 PR观察构建报告里是否只包含受影响的 stories。最容易踩的坑是 CI 浅克隆导致增量策略失效配置阶段一定要把fetch-depth: 0加上。下一步可以做的是给项目补一个“快照成本趋势”脚本把每次构建的快照数收集起来形成按月报表。这样后续无论组件库怎么膨胀成本都能保持在可控范围内。