企业官网建设流程全解析

Chromatic 按快照计费，账单上涨通常不是代码写多了，而是快照策略太松。Storybook 全量出图、多 viewport、多主题、每次 push 都跑完整流水线，几项叠加，月账单很快就上去了。其实大多数组件库根本不需要“每次全量截图”，把无效快照删掉、把触发范围收窄，成本可以显著下降。

这次我们从一个组件库项目的实际优化过程出发，分享一套适用于 Chromatic、Percy、Lost Pixel 以及 Playwright 自建基线的通用降本方案。核心思路归纳成一句话：把“视觉回归”的限制条件从“能截就截”改成“必须截才截”。文章会讲清楚成本模型、三层优化手段、CI 配置、验证方法和常见坑位，让你在现有工具上直接落地，不需要换平台。

1. 视觉测试成本模型：先把钱花在哪里搞清楚

视觉测试工具的计费单位通常不是“构建次数”，而是Snapshot（快照）。Chromatic 的套餐和超额计费围绕快照数量展开，Percy 的按量逻辑也类似。一次快照是一次完整的截图 + 基线对比，会占用额度、产生存储、参与构建记录。所以成本优化的本质，是减少快照总数。

一个组件库项目的月度快照消耗，可以用下面这个公式估算：

月度快照总量 ≈ Story 总数 × 单个 Story 平均视口变体数 × 平均模式变体数 × CI 运行次数

四个变量里，任何一个放大，成本都会成倍上涨。很多团队遇到的情况是“四个变量一起涨”：Story 数量随组件库膨胀，从 200 涨到 1000；Storybook 配置了 3 个 viewport；组件支持 light / dark 两套主题；CI 里每次 push 都全量跑一次 Chromatic。

结果就是一个 Story 可能产出 6 张快照，1000 个 Story 一轮就跑 6000 张快照。如果团队一天合入 10 个 PR，一个月轻松突破十万甚至几十万快照。账单高不是因为工具贵，而是因为策略默认全量。

所以在动手优化前，建议先建一个成本基线：

1. 登录 Chromatic / Percy 控制台，找到最近 30 天的快照用量数据。
2. 统计当前 Storybook 里有多少个 stories。
3. 统计 CI 中视觉测试任务每天跑多少次。
4. 把四个变量填入公式，算出当前理论快照量。

有了基线，后续每做一次优化，都可以对比快照数的变化，而不是凭感觉判断效果。

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 Meta<typeof Button>; export default meta; type Story = StoryObj<typeof 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 Meta<typeof 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-changed：

npx 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/checkout@v4 with: fetch-depth: 0 - uses: actions/setup-node@v4 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?id=date-picker--default&viewMode=story'); 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 里做视觉回归。

思路不复杂：

1. 构建 Storybook 静态站点。
2. 在本地启动静态服务。
3. Playwright 打开iframe.html?id=<storyId>&viewMode=story。
4. 调用toHaveScreenshot生成或对比基线。
5. 把基线截图提交到 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?id=components-button--primary&viewMode=story` ); 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. 优化后效果验证：怎么确认没有漏检

成本降下来之后，要回答一个关键问题：视觉回归的质量有没有下降？光看快照数量减少还不够，必须让团队确认“真正重要的页面仍然在对比”。

推荐建立一套效果验证清单，每次优化后执行一次：

1. 在测试环境故意修改某个核心组件的颜色，确认视觉任务失败。
2. 故意修改一个无关组件，确认 turboSnap 没有触发全量截图。
3. 检查 Chromatic 的构建报告，确认当天 snapshot 数量明显减少。
4. 抽查 10 个关闭快照的 story，确认它们确实不需要视觉对比。
5. 确认核心用户路径，比如首页、登录页、结算页仍然有基线快照。

另外，需要注意稳定性问题。如果视觉测试频繁因为动画、字体加载、网络请求而出现“假 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/checkout@v4 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 视觉测试的时间通常也会同步下降。观察性能时，重点看这几个指标：

如果发现--only-changed开启后任务耗时并没有下降，优先排查 Git 历史是否完整、构建配置是否正确读取依赖图。monorepo 项目中，跨包依赖未正确声明会导致 turboSnap 把所有包都标记为受影响，这时需要检查chromatic.config的项目根目录配置。

10. 常见问题与排查方法

11. 视觉测试降本最佳实践

把整套方案落地时，建议按下面的顺序执行，避免一次性改太多导致团队失去信心：

1. 先花半天拉取当前快照量和成本基线。
2. 建立“story 是否需要视觉快照”的评审规则，统一在组件库文档中标注。
3. 先删除明显无价值的 stories 快照，看一周效果。
4. 收敛全局 viewport 和主题模式，优先保留核心断点。
5. 开启 turboSnap，并验证增量命中。
6. 用 Playwright 交互断言替代部分非像素型用例。
7. 把核心页面和关键组件留在托管平台，低风险组件逐步迁到自建基线。
8. 每周固定时间检查一次快照统计和 CI 耗时，发现反弹及时调整。

合规方面，也要做几个收口：

• 视觉测试账号使用脱敏后的测试数据，不要在截图里暴露真实用户、手机号、邮箱等个人信息。
• 如果测试环境接入第三方系统，确保数据来源合法，避免把生产数据直接带到视觉测试平台。
• 外部平台的项目令牌统一放入 CI 的 Secrets，不要写进代码仓库。
• 涉及用户肖像、版权素材的页面，不要提交到公网可访问的视觉测试项目。

这些边界不只是成本问题，也关系到测试数据保护和团队安全习惯。

12. 总结与下一步

这次我们拆解的，其实不是“怎样少付钱”，而是“怎样让视觉回归只在必要的时候产生必要的结果”。删除无效快照、收敛 viewport 和主题、开启增量模式、把非视觉用例移到其他测试层，四步做到位，快照量通常能降到原来的十分之一左右。这个结论在 Chromatic 上成立，在 Percy、Lost Pixel、Playwright 自建基线上同样成立。

最值得先验证的是 turboSnap 的命中效果：打开一个改动最小的 PR，观察构建报告里是否只包含受影响的 stories。最容易踩的坑是 CI 浅克隆导致增量策略失效，配置阶段一定要把fetch-depth: 0加上。

下一步可以做的，是给项目补一个“快照成本趋势”脚本，把每次构建的快照数收集起来，形成按月报表。这样后续无论组件库怎么膨胀，成本都能保持在可控范围内。