企业官网建设流程全解析

Storybook 启用可视化测试：用storybook add一键安装 Chromatic 官方插件

Storybook 官方在 Visual tests 指南 中提供了一套可视化测试（Visual Testing）接入方案：安装由 Storybook 团队维护的官方插件@chromatic-com/storybook，即可把每个 story 自动变成基于像素的快照测试，并在云端进行跨浏览器对比。本文围绕仓库中嵌入该方案的安装片段 docs/_snippets/chromatic-storybook-add.md，讲解它在 npm、pnpm、yarn 三种包管理器下的标准写法，并深入 CLI 源码剖析storybook add到底做了什么，以及安装后如何启用面板、接入 CI、做基线配置，让你能直接在自己的 Storybook 项目中落地可视化测试流程。

这个片段在文档体系中扮演的角色

该片段本身是 Storybook 文档站点里被多处复用的"可执行代码片段"（CodeSnippets），它被正式引用在 docs/writing-tests/visual-testing.mdx 的Install the addon小节中。因此，从仓库文档结构看，storybook add @chromatic-com/storybook就是 Storybook 官方推荐的可视化测试起步命令——它不是一条普通的npm install，而是会连同插件注册一起处理的"自动安装"入口。

它的使用场景非常明确：你的项目已经初始化了 Storybook（无论 Webpack 还是 Vite 构建器、无论 React/Vue/Angular 等哪种渲染器），现在希望以最小的手工操作获得可视化回归测试能力。执行这一条命令后，插件会被写入 devDependencies，并自动登记到 Storybook 的addons配置中，随后你在启动的 Storybook 界面里就能看到新增的 Visual Tests 面板。

三种包管理器下的安装命令

仓库片段 docs/_snippets/chromatic-storybook-add.md 给出了覆盖 npm、pnpm、yarn 的统一写法：

npm

npx storybook@latest add @chromatic-com/storybook

pnpm

pnpm dlx storybook@latest add @chromatic-com/storybook

yarn

yarn dlx storybook@latest add @chromatic-com/storybook

三条命令在语义上等价，只是借助各自包管理器自带的远程执行工具（npx/dlx）拉取并运行 CLI：

两点值得注意的细节：

• 命令中的storybook@latest明确要求从 registry 临时获取最新版 CLI 再执行（而非使用本地已安装的storybook二进制），这正是dlx/npx的设计初衷——把包拉取到临时环境运行。仓库中 add.ts 的PostinstallOptions注释也印证了dlx/npx这种"ephemeral environment"取包模式。
• 如果你想同时传入多个插件，例如storybook add @chromatic-com/storybook another-addon，目前只会安装第一个指定的插件。这一限制被明确记录在 自动安装 addon 文档 的警告块中，官方称会在未来版本修复。

storybook add命令的实际执行流程

为什么不直接npm install @chromatic-com/storybook？因为add子命令要做的远不止装包。以当前仓库中该命令的实现 code/lib/cli-storybook/src/add.ts 为据，它按顺序完成以下工作：

1. 解析插件名与版本号：通过getVersionSpecifier把输入拆成"包名"与"可选版本"。它同时支持指定版本，例如storybook add @storybook/addon-docs@7.0.1，版本号会拼在@之后（见 add.ts）。
2. 定位 Storybook 配置：读取你的.storybook/main配置文件与 preview 配置，如果找不到配置目录会直接报错，并提示可用--config-dir标志指定；如果找不到main.js|ts则终止。
3. 查重与确认：如果目标插件已经存在于addons数组中（checkInstalled），CLI 会提示"是否仍然要安装一次"，由用户确认；传入--yes可跳过交互直接执行。
4. 决定安装版本：源码通过isCoreAddon判断插件包是否在 Storybook 内置的版本清单versions中——若属于 Storybook 核心插件且未指定版本，则自动对齐你当前 Storybook 的安装版本；否则（@chromatic-com/storybook属于 Chromatic 生态而非 Storybook 核心包，故落入此分支）会去 npm registry 查询该包的最新版本。若检测到核心插件版本与当前 Storybook 版本不一致，还会打印警告。
5. 安装依赖：以 devDependencies 的形式安装，并依据解析结果自动带上版本范围（如^前缀）。这正是 CLI 内部对packageManager.addDependencies的调用所完成的工作。
6. 自动注册：通过setupAddonInConfig把插件写入配置文件里的addons字段（等价于手动往.storybook/main.js|ts中追加一条），随后即可在 Storybook 中生效。手动方式的完整等价操作示例见 install-addons 文档 与 addons 配置字段说明。
7. 触发安装后钩子：对 Storybook 核心插件，安装完成后还会运行postinstallAddon，处理那些需要额外配置的插件的后续动作。

也就是说，你执行一次storybook add @chromatic-com/storybook，CLI 在同一轮内替你完成了"确定版本、安装为 devDependencies、登记进 addons 配置"三步。命令对应的单元测试可参考 code/lib/cli-storybook/src/add.test.ts，其中覆盖了版本解析、重复安装询问等分支行为。除可视化测试外，同一机制也用于安装其他官方/社区插件，如@storybook/addon-a11y、@storybook/addon-mcp、@storybook/addon-vitest等，可对比仓库中其他安装片段（例如 addon-a11y 安装片段）印证。

安装完成后：启用并连接你的项目

插件安装并注册完成后，重启 Storybook（npm run storybook或你项目配置的开发脚本），侧边栏/工具栏就会出现新的Visual Tests面板。

启用流程分三步：

1. 登录 Chromatic 账户：在插件面板中完成登录。如果没有账户，可在登录流程中一并创建。
2. 选择或创建项目：登录后面板会列出你的 Chromatic 账户及关联项目，选择一个既有项目，或新建一个。

3. 首次构建基线：点击"Catch a UI change"按钮执行第一次可视化测试构建。这一次构建会为你的每个 story 生成基线快照（baseline），后续再次运行测试时，云端会将新快照与基线对比，从而找出像素级差异。

之后每次改动代码，可以通过扩展后的测试小组件或插件面板右上角的运行按钮再次把 stories 发送到云端截图并检测视觉变化。如果检测到 🟡 高亮的变更，可在面板中核对具体差异像素：变化符合预期就本地接受为新的基线，不符合就修复后重跑。接受的基线会与远程同步，供检出新分支的团队成员复用——这就是"接受一次，CI 不重复审核"的设计基础（详见 docs/writing-tests/visual-testing.mdx）。

把可视化测试自动化进 CI（GitHub Actions）

插件面板适合开发期即时检查，而合并前的最终把关则推荐放进 CI。仓库提供了配套的 GitHub Actions 工作流模板，见 docs/_snippets/chromatic-github-action.md，核心内容如下：

# Workflow name name: 'Chromatic Publish' # Event for the workflow on: push # List of jobs jobs: test: # Operating System runs-on: ubuntu-latest # Job steps steps: - uses: actions/checkout@v6 with: fetch-depth: 0 - uses: actions/setup-node@v6 with: node-version: 24 cache: 'yarn' - run: yarn #👇 Adds Chromatic as a step in the workflow - uses: chromaui/action@latest # Options required for Chromatic's GitHub Action with: #👇 Chromatic projectToken, projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }} token: ${{ secrets.GITHUB_TOKEN }}

工作流要点：

• fetch-depth: 0：完整克隆历史，便于 Chromatic 定位到正确的基线提交做差异比较；
• projectToken：通过仓库 SecretCHROMATIC_PROJECT_TOKEN提供，用于向 Chromatic 鉴权。如果没有通过storybook add关联过 CLI/CI 项目，需先用 chromatic-install 片段 中的方式安装chromatic命令行包并完成 token 配置；
• token：传入GITHUB_TOKEN，让 Chromatic 能把检查结果（UI Tests 徽章）回写到你的 PR 上。

配置成功后，你的 Pull Request / Merge Request 会带上 UI Tests 状态徽章，用于提示团队"存在未验证的 UI 变更或测试错误"。你还可以在 Git 平台把该检查设为 required，从流程上阻止意外的 UI 缺陷被合并进主干。

可选的精细化配置：chromatic.config.json

插件与 Chromatic CLI 共用项目根目录下的chromatic.config.json做精细化配置，覆盖大多数场景时保持默认即可。Visual tests 文档列出的常用选项如下：

组合示例：

{ "buildScriptName": "deploy-storybook", "debug": true, "projectId": "Project:64cbcde96f99841e8b007d75", "zip": true }

需要说明的是：storybook add在项目关联后会自动写入并维护projectId，通常无需手工编辑；buildScriptName、zip等则适合在插件注册完成、接入 CI 时按项目规模调整。

与快照测试的差异及更多相关文档

Visual tests 与常见的快照测试（snapshot tests）本质不同：快照测试比较每个 story 渲染产物的 HTML 标记与基线，改动代码不一定产生可见变化，因此容易出现误报；而可视化测试比较每个 story 实际渲染出的像素与基线，测试的是用户真实看到的东西，更贴近真实体验、也更易维护。这也是 Chromatic 方案在组件回归把关上的核心价值所在。

围绕可视化测试及与其配合的测试体系，可继续查阅仓库内下列文档：

• Visual tests 完整指南：安装、启用、运行、评审变更到 CI、PR 检查的端到端流程；
• 安装 addon 通用指南：storybook add的适用边界与手动安装、移除 addon 的方法；
• CLI 选项参考：add子命令及--config-dir、--yes、--skip-install等配套参数；
• main 配置 addons 字段：addons 数组支持字符串与对象两种登记形式的语法细节；
• 快照测试指南：与可视化测试互补的 HTML 级回归手段。

按上述步骤完成storybook add @chromatic-com/storybook之后，你的项目便具备了"开发期面板即时检查 + 合并前 CI 自动巡检"的双层可视化回归能力，UI 变更在进入主干前都能得到像素级审查。