如果你的 Chromatic 账单一直在涨第一反应不应该是限制团队使用而是去看 CI 里到底上传了多少份不该上传的快照。Chromatic 是对接 Storybook 的视觉测试和 UI 审核平台核心成本逻辑是按快照构建量、并发数和审查事件计费。所以成本优化的关键是把“无效快照”数量降下来而不是把团队业务量降下来。这篇文章会围绕“如何把视觉测试账单压到原来的十分之一”展开。整套思路不只是针对 ChromaticPercy、Argos、Playwright Visual Regression、Lost Pixel 这类工具也能复用。文章会先拆解视觉测试账单的构成再给出一套可落地的 CI 配置、通用影响图脚本和批量任务方案最后补充常见问题和排查清单。如果你管理的前端项目已经接入了 Storybook或者正在评估视觉测试工具这篇文章可以直接作为成本控制的操作手册来用。1. 视觉测试的成本结构先知道账单花在哪很多团队看到视觉测试账单上涨第一反应是“测得太多了”然后开始砍故事、砍页面。但更合理的第一步是先搞清楚账单里每一个计费项是怎么产生的。1.1 按快照和构建量计费Chromatic 这类视觉测试平台通常不是按“API 调用次数”计费而是按“快照”和“构建”的累计规模来计费。一次构建里包含多少个 Story就会生成多少张组件截图每次 PR 更新、每次 push、每次并发跑测试都会产生新的构建记录。可视化项目的典型成本构成如下成本驱动项产生方式是否可优化Story 快照数Storybook 每次 build 后每个 Story 生成一张基础快照可优化PR 构建次数每次 push 到 PR 分支触发一次快照构建可优化并发构建数量CI 多分片同时跑视觉测试可优化审查事件UI Review 中人工确认、评论、标记变化不可过度压缩云端渲染时长云端对快照做完整渲染和对比与快照数量强相关从上面可以看到真正能优化的空间集中在“快照数量”和“构建次数”上。而 UI 审查本身是视觉测试的核心价值不建议为了省钱把这部分砍掉。1.2 账单失控的三个典型场景账单越滚越大通常不是工具贵而是使用姿势导致的。最常见的有三种场景一每个功能分支都全量构建 Storybook。团队在 GitHub 上每开一个 PRCI 就执行一次npx chromatic把整个 Storybook 的所有 Story 都上传一遍。假设项目有 200 个组件、400 个 Story一次全量构建就是 400 张快照。10 个人同时开发一个下午就能产生几千张快照的消耗。场景二把“视觉测试”和“组件单元测试”混在一起。有的团队为了保证覆盖给一个组件的每个状态都单独建 Story比如表格的行 hover、行选中、空态、loading、error。这些状态确实需要验证但它们更适合用组件测试或快照测试在本地做而不是全部上传到视觉测试平台。场景三CI 开了大量并发分片。为了缩短构建时间团队会把测试平均分到 4 到 8 个并发任务。视觉测试平台往往按并发构建数计费或限流。并发从 1 加到 8速度是上来了成本也可能按倍数上涨。出现这三个场景先不要急着换工具优化 CI 策略通常能把成本降下来。2. 降低视觉测试成本的策略清单视觉测试成本优化的核心原则只有一句话让必须上传的快照更少让不需要上传的快照在本地结束。下面是六条直接可用的优化策略。策略操作方式效果基线分离只在主分支做全量快照PR 分支只上传有变化的 Story消除重复全量构建改动感知用 Git diff 和组件依赖图筛选受影响的组件快照量从全量变为增量本地断言把纯组件状态用组件测试或快照测试在本地跑减少云端快照依赖并发控制限制 CI 视觉测试的并发分片数量避免并发费用膨胀跳过无关键构建文档、注释、样式常量变更时不触发视觉测试减少无意义的构建记录合并冗余 Story把同一组件的多个 Story 改为交互式控制板单组件只留一份基础快照这六条策略可以独立使用也可以组合使用。实际项目中收益最大的是“基线分离 改动感知”的组合。基线分离的思路完整快照只需要在主分支合并后生成一次然后作为比较基线存好。PR 分支上只需要上传“真正发生视觉变化”的 Story和基线对比。改动感知的思路不依赖人工判断“这次改了哪些组件”而是由脚本根据 Git 文件变化自动算出影响范围只对受影响组件执行视觉测试。下面两节分别给出 Chromatic 和通用工具的实现方式。3. Chromatic 实例从全量构建到增量发布Chromatic 本身提供了 TurboSnap 类的能力可以在 git 仓库中分析模块依赖跳过没有变化的 Story 构建。但如果 CI 配置不对这个能力不会被充分利用。这里给出一套可以直接上手的 GitHub Actions 配置。3.1 主分支与 PR 分支分离先按“主分支全量构建PR 分支增量上传”的方式设计流程name: visual-test-ci on: push: branches: [main] pull_request: jobs: visual: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 with: fetch-depth: 0 - uses: actions/setup-nodev4 with: node-version: 20 - run: npm ci - name: Chromatic deployment run: npx chromatic --project-token${{ secrets.CHROMATIC_PROJECT_TOKEN }}这段配置的关键点有两个fetch-depth: 0必须拉取完整 git 历史因为改动检测依赖 commit 对比。主分支和 PR 分支使用同一个命令Chromatic 会自动识别基线构建。当你第一次在 PR 分支上跑时Chromatic 会基于主分支最近一次成功构建做差异对比。只要组件的模块依赖没有变化对应 Story 不会重新上传快照量会直接从“全量”变成“增量”。3.2 利用 only changed 机制控制上传范围Chromatic 的 CLI 支持只上报有变化的 Story。在 Storybook 版本较新、Chromatic 版本兼容的情况下可以通过参数减少每次构建的数据量npx chromatic --project-token$CHROMATIC_PROJECT_TOKEN --only-changed--only-changed会让构建服务只处理发生变化的 Story而不是把整个 Storybook 重新上传。如果项目里 Storybook 体积比较大这个参数能明显降低构建耗时和上传带宽。注意不同版本的 Chromatic CLI 对参数的支持程度不一样落地前先执行npx chromatic --help确认当前版本是否支持。3.3 跳过无关构建有一类提交不应该触发视觉测试。比如只改了 README、只改了.github/workflows、只改了代码注释。这种提交如果也跑一次 Chromatic就是白白消耗一次构建配额。可以在 CI 脚本里做预判# 伪代码需要按项目实际目录调整 if git diff --quiet $BASE $HEAD -- src/; then echo src 目录没有变化跳过视觉测试 npx chromatic --skip else npx chromatic --project-token$CHROMATIC_PROJECT_TOKEN fi--skip会让 Chromatic 记录一次跳过不产生快照费用。这个操作特别适合 monorepo 中多个子包共用同一个工作流的场景。4. 通用视觉测试工具影响图驱动的“改动感知”测试Chromatic 有内置的模块依赖分析但其他视觉测试工具不一定有。要实现“只测受影响的组件”可以自己写一个影响收集脚本再把过滤结果喂给测试工具。这套方法适用于 Percy、Argos、Playwright Visual Regression、Lost Pixel 等所有支持命令行运行的工具。4.1 影响收集脚本以下脚本根据 Git 差异提取变更涉及的组件目录// scripts/affected-components.js const { execSync } require(node:child_process); const base process.env.CI_MERGE_BASE || origin/main; const head process.env.GITHUB_SHA || HEAD; const changedFiles execSync(git diff --name-only ${base}...${head}, { encoding: utf8, }) .split(\n) .filter(Boolean); const components new Set(); changedFiles.forEach((file) { // 按自己仓库的目录结构调整 const match file.match(/^src\/components\/([^/])/); if (match) components.add(match[1]); }); console.log([...components].join(\n));运行方式node scripts/affected-components.js输出结果是一组组件目录名例如Button、Modal、Table。接下来可以把这组结果作为下游测试命令的过滤条件。4.2 在 CI 中批量执行受影响组件测试拿到受影响组件后在 CI 里循环执行视觉测试命令# 通用模板按自己工具的测试命令替换 AFFECTED_COMPONENTS$(node scripts/affected-components.js) if [ -z $AFFECTED_COMPONENTS ]; then echo 没有受影响的组件跳过视觉测试 exit 0 fi for component in $AFFECTED_COMPONENTS; do echo 运行 $component 的视觉测试 npx percy exec -- npm run visual:test -- --component$component done这段脚本的核心价值是把视觉测试从“全量兜底”变成“改动兜底”。每个 PR 只处理真实变化的组件快照数量自然减少。4.3 Playwright 视觉测试的过滤示例如果你用的是 Playwright Visual Regression可以在测试文件里读取环境变量只生成变化组件的截图用例// visual.spec.js import { test, expect } from playwright/test; const affected (process.env.AFFECTED_COMPONENTS || ).split(,).filter(Boolean); test.describe(改动组件视觉回归, () { for (const name of affected) { test(${name} 渲染快照, async ({ page }) { await page.goto(/storybook/iframe.html?id${name.toLowerCase()}--default); await expect(page).toHaveScreenshot(${name}.png, { animations: disabled, fullPage: true, }); }); } });这个方案的核心思路就是“影响图 白名单过滤”。即使视觉测试工具自身不带 TurboSnap也能通过外层脚本获得接近的增量效果。5. 批量任务与并发配额管理视觉测试一旦接入 CI很快会遇到批量任务和并发控制的问题。如果不是单人项目CI 里同时跑的路径会很多不控制并发就等于放任成本增长。5.1 限制 CI 并发分片GitHub Actions 的矩阵策略很方便但容易把并发拉得很高。建议视觉测试单独作为一个 job不和其他测试混在一个矩阵里并且限制最大并发。jobs: visual-test: runs-on: ubuntu-latest strategy: max-parallel: 2 matrix: shard: [1, 2] steps: - uses: actions/checkoutv4 - run: npm ci - run: npm run visual:test -- --shard${{ matrix.shard }}把max-parallel设为 2而不是 8能让构建时间保持在可接受范围同时避免并发成本翻倍。5.2 用合并队列减少重复构建很多团队的 PR 流程是开发者不断 push 新 commit每 push 一次就触发一次视觉测试。如果同一个 PR 里有 20 次 commit就会产生 20 次快照构建。更经济的做法是只在 PR 被合并进主分支时执行视觉测试或者使用 GitHub Merge Queue 合并多次 push 后再统一测试。5.3 成本观测指标要量化优化效果建议每次构建后在 CI 日志里输出以下指标指标说明snapshot count本次构建产生的快照总数changed component count本次实际发生变化的组件数skipped story count被跳过未构建的 Story 数build time本次视觉测试构建耗时upload bytes上传到云端的快照体积有了这些指标对比优化前和优化后的数据就能直接算出成本下降比例。6. 资源占用与性能观察维度视觉测试不只是“贵不贵”的问题还涉及 CI 资源占用和整体耗时。从工程角度看需要观察四个维度构建时间。快照数量越多Storybook 构建越慢。如果全量构建耗时超过 5 分钟增量构建优化后往往能降到 1 分钟以内。观察时间差是判断优化是否有效的最直接方式。CPU 和内存占用。视觉测试通常会在本地先渲染页面再截图渲染进程数量越多内存越高。如果 CI Runner 内存只有 4GB建议把并发控制在 2 以内否则会出现渲染进程被杀、快照不完整的问题。上传体积。快照图片和 Storybook 静态资源都要上传到云端。上传体积和网络耗时直接相关也影响构建配额。优化后上传体积应该明显下降否则说明过滤逻辑没有生效。构建队列情况。如果项目有大量 PR 同时触发视觉测试会出现排队现象。排队时间过长时要考虑提升构建速度而不是扩张并发因为扩张并发等于扩大成本。最终还是要落到本机或 CI 实际数据上不同项目的组件数量、图片压缩率、页面复杂度差异很大不能照搬别人的数字。7. 常见问题与排查方法问题现象可能原因排查方式解决方案PR 分支构建仍然包含全部 Storyfetch-depth 设置不够git 历史不完整检查 checkout 步骤是否设置 fetch-depth: 0修改 fetch-depth 后重新触发没有变化的组件也被重新构建组件依赖了公共工具函数公共函数变更触发级联查看模块依赖图确认变更文件是否被公共模块引用对纯函数模块配置忽略范围账单没有下降反而变多CI 并发分片增加而且没有限制 max-parallel查看运行记录中的并发任务数调整矩阵并发上限npx chromatic --skip没有生效CLI 版本太旧或参数名不匹配执行npx chromatic --help按版本文档调整参数本地视觉测试通过云端却很多变化本地字体、分辨率、抗锯齿设置与云端不一致对比本地和云端截图环境统一 Docker 镜像和浏览器版本改动了组件测试但影响收集脚本没识别到目录匹配规则不匹配实际仓库结构打印 changedFiles 原始列表调整正则匹配规则Playwright 测试全部通过但控制台出现未捕获异常页面组件在渲染过程中报错但不影响截图查看浏览器 console 日志在测试中加入页面错误监听CI 排队时间越来越长并发被限制后构建吞吐下降查看构建队列耗时优化 Storybook 体积而不是提高并发排查的顺序建议是先确认 Git 差异是否正确再确认过滤脚本是否命中最后确认测试工具是否按预期跳过。8. 最佳实践与合规提醒视觉测试工具会把组件截图上传到云端因此在使用时需要注意几个原则。测试素材不能带入真实用户信息。视觉测试通常用 mock 数据填充组件不要在 Story 里写死真实用户姓名、手机号、邮箱、地址等敏感信息。如果有真实数据页面截图前要做脱敏处理。版权素材不能随意上传。如果组件里包含字体、图片、音视频等第三方素材要确认是否允许在 SaaS 平台渲染和存储。企业级项目建议在采购前检查服务协议中的数据存储范围。组件 Story 不等于完整页面。不要把整条业务链路的页面全部堆进 Storybook。完整页面更适合用 E2E 测试在本地或内网环境做快照只有真正需要视觉审核的核心组件才上传到视觉测试平台。降低快照数量的同时也要保留一条最小可运行基线。建议至少保留一套只包含核心组件的主分支构建配置避免为了省钱把视觉测试完全关闭。SQL、数据库、业务逻辑不在视觉测试范围内。视觉测试只管“看起来对不对”不负责“跑起来对不对”。不要依靠视觉测试去覆盖组件单元测试该做的事情否则成本上去了覆盖率却没有实际提升。9. 总结与下一步这一套方案最值得先尝试的是“主分支全量构建、PR 分支增量上传”和“影响组件过滤脚本”两个组合拳。它们不需要改动业务代码只需要调整 CI 配置就能把快照量从全量变成增量这也是账单下降最明显的一步。最容易踩的坑有两个一是 checkout 时忘了fetch-depth: 0导致 git 差异对比失败增量构建失效二是只改脚本不过滤CI 看起来在跑实际上所有 Story 还在照常上传。优化后一定要在构建日志里对比 snapshot count 和 skipped story count。后续可以考虑继续扩展的方向包括把影响图脚本升级为更完整的模块依赖分析将视觉测试结果与已有设计系统组件进行联动或把成本监控指标接入团队的报表看板。建议先把今天的优化配置保存一组基线数据下个迭代再对比一次控制效果会非常直观。