使用 GitHub Actions 与 Chromatic 实现 Storybook 持续发布与视觉回归测试

在团队协作开发组件库或 UI 应用时，把构建产物 Storybook 发布到线上供所有人审阅，是保证"所见即所得"的关键一环。本篇技术指南基于当前仓库 docs/sharing/publish-storybook.mdx 章节及其核心代码片段 chromatic-github-action.md，完整讲解如何在项目根目录创建 .github/workflows/chromatic.yml 工作流，利用 GitHub Actions 在每次 push 时自动构建并发布 Storybook 到 Chromatic 云端，从而让每个 Pull Request 都能自动生成可访问的 UI 预览地址。读完本文你将掌握工作流每个字段的含义、fetch-depth: 0 等配置背后的原理、Secrets 安全注入方式，以及如何在本仓库源码中找到真实的 Chromatic 配置佐证。

一、发布流程概览：从静态构建到云端托管

Chromatic 是一款面向 Storybook 的发布与视觉测试托管服务。官方文档把整个流程划分为清晰的三个步骤，本文要讲解的 GitHub Actions 工作流属于其中的最后一步"自动化发布"，但前两步同样不可缺少：

1. 构建静态站点：在项目根目录执行构建命令（如 npm run build-storybook），Storybook 会生成一份可由任意 Web 服务器托管的静态 Web 应用，具体命令见仓库片段 build-storybook-production-mode.md；如使用 Angular 建议改用其官方 builder 构建。
2. 首次手动发布：通过 npm install chromatic --save-dev（pnpm 为 pnpm add --save-dev chromatic，yarn 为 yarn add --dev chromatic，见 chromatic-install.md）安装 Chromatic CLI，然后运行 npx chromatic --project-token=<your-project-token> 把 <your-project-token> 替换为你自己的项目 Token。成功后终端会输出类似 Build 1 published. 的结果，并提供在线预览链接。
3. 配置 CI 自动发布：这是本指南的主体。将 Chromatic CLI 发布步骤固化为 GitHub Actions 工作流，让推送代码时自动发布，并能在 PR 检查里看到发布后的 Storybook 链接。

仓库在 code/chromatic.config.json 中提供了真实可参考的 Chromatic 配置样例，展示了 Token 的另一种注入形态，后面会详细对比。此外，若想把 Chromatic 视觉测试能力深度集成进 Storybook 项目，官方也提供了 npx storybook@latest add @chromatic-com/storybook 一键添加的方式（npm/pnpm/yarn 变体见 chromatic-storybook-add.md），可同时获得本地 Storybook 内的 "Visual Tests" 面板体验。

二、创建 GitHub Actions 工作流：完整 YAML 逐段拆解

在项目根目录下新建 .github/workflows/chromatic.yml 文件，写入以下内容（即仓库代码片段 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 }}

该工作流本质上是"检出代码 → 安装依赖 → 交给 Chromatic Action 构建并发布"三步流水线。下面逐段说明每个配置项的职责与注意事项。

1. 触发器与运行环境

on: push

工作流监听 push 事件触发。这意味着每当开发者向仓库推送提交（包括推送到 PR 分支），都会触发一次新的 Chromatic 构建与发布。由于 Chromatic 会把构建与 git 提交关联起来，每次 push 都会生成对应这次提交的独立构建版本，这是实现"按 commit 版本化与回溯"的前提。

runs-on: ubuntu-latest

指定任务在 GitHub 托管的 Ubuntu 最新版运行器上执行。Storybook 构建与 Chromatic 上传不依赖特定操作系统，使用 Ubuntu 即可覆盖绝大多数场景。

2. 检出代码：为什么必须 fetch-depth: 0

- uses: actions/checkout@v6
  with:
    fetch-depth: 0

这里有两个值得留意的细节：

• 版本 @v6：这是当前仓库文档中引用的版本号。GitHub Actions 官方推荐固定主版本号（如 @v6）而非 @latest，以便在可控前提下获得主版本内的兼容更新；你也可以根据实际需要选择 @v3、@v4 等可用主版本。
• fetch-depth: 0：该选项让 actions/checkout 拉取完整的 git 历史（包括所有分支与标签）而非仅检出当前 commit。对 Chromatic 而言这几乎必不可少：它需要比较"当前提交"与"上次基线（baseline）"之间到底有哪些组件/Story 发生变化，从而确定本次需要执行的视觉测试范围，并生成差异快照与回归报告。如果只检出浅克隆（默认 fetch-depth: 1），Chromatic 将缺少对比所需的祖先提交信息，导致无法正确计算变更。

3. 配置 Node.js 与包管理器缓存

- uses: actions/setup-node@v6
  with:
    node-version: 24
    cache: 'yarn'
- run: yarn

• node-version: 24：设置 Node.js 运行版本，文档当前以 24 为例，可按项目实际要求的 LTS 版本调整。
• cache: 'yarn'：让 setup-node 自动缓存 Yarn 依赖，显著缩短后续运行时的依赖安装耗时。它假定项目使用 Yarn 作为包管理器且根目录存在 yarn.lock。
• run: yarn：安装项目依赖。若项目使用 npm，应将 cache 改为 npm 并把该行替换为 npm ci 或 npm install；使用 pnpm 时同理改为 pnpm install。选择与你的 Storybook 项目一致的包管理器即可。

4. 调用 Chromatic Action 发布

- uses: chromaui/action@latest
  with:
    projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
    token: ${{ secrets.GITHUB_TOKEN }}

这是整条流水线的核心。chromaui/action 是 Chromatic 官方提供的 GitHub Action，它替你完成了"构建 Storybook → 上传快照 → 触发云端视觉测试 → 回写 PR 检查状态"等一系列操作，等价于在 CI 中自动执行手动流程里的 npx chromatic --project-token=<your-project-token> 命令。

两个必需参数的含义分别是：

参数	取值	作用
projectToken	${{ secrets.CHROMATIC_PROJECT_TOKEN }}	Chromatic 项目专属令牌，用于标识并把构建产物上传到你的 Chromatic 项目。不应硬编码在 YAML 里，必须通过 GitHub Secrets 注入
token	${{ secrets.GITHUB_TOKEN }}	GitHub 自动生成的临时令牌，授权 Chromatic 以当前任务身份向 PR/commit 写入状态检查与评论，从而在你的 PR Checks 中显示构建结果与可点击的预览链接

关于 GITHUB_TOKEN：它由 GitHub 在每次任务运行时自动创建并注入 secrets 上下文，无需你在仓库设置里手动配置；其默认权限足以支撑 Chromatic 发布状态回写。而 CHROMATIC_PROJECT_TOKEN 则必须由你自行创建。

三、配置项目 Token：把 Secrets 安全地注入工作流

projectToken 属于敏感凭据，官方文档明确建议使用 GitHub 加密 Secrets 而非硬编码。具体操作如下：

1. 登录 Chromatic，为当前 Storybook 项目生成唯一的 project-token。
2. 打开 GitHub 仓库页面 → Settings → Secrets and variables → Actions → New repository secret。
3. 创建名为 CHROMATIC_PROJECT_TOKEN 的 Secret，把上一步生成的 Token 粘贴进 Value 后保存。
4. 工作流中通过 ${{ secrets.CHROMATIC_PROJECT_TOKEN }} 引用该变量即可。

Secrets 是 GitHub 提供的加密环境变量，一旦创建，任何人对具体值的可见性都会受到严格限制，从而避免把 Token 明文写入版本库造成泄露。这一做法直接呼应文档 publish-storybook.mdx 中"Secrets are secure environment variables"的提示——需要创建项目 Token 的账号体系（GitHub / GitLab / Bitbucket 或邮箱）以及在 Chromatic 侧生成令牌的环节，都应在配置 CI 前提前完成。

与"配置文件方式"的对比：仓库内真实的 chromatic.config.json

值得补充的是，Token 除通过 GitHub Secrets 注入外，还可写入项目根目录的 chromatic.config.json。本仓库自身就携带了这样一份真实配置，见 code/chromatic.config.json：

{
  "$schema": "https://www.chromatic.com/config-file.schema.json",
  "buildScriptName": "storybook:ui:build",
  "onlyChanged": true,
  "projectId": "Project:635781f3500dd2c49e189caf",
  "projectToken": "80b312430ec4",
  "storybookBaseDir": "code",
  "zip": true
}

从这个实际运行于本仓库的配置样例中，可以观察到若干对 CI 发布有参考价值的字段：

• projectToken / projectId：明文形式的项目标识。由于本仓库需要公开用于演示，才以明文存储；对普通项目而言，推荐将其放入 CI Secrets 环境变量，优先使用 ${{ secrets.CHROMATIC_PROJECT_TOKEN }} 注入，避免 Token 随源码一起分发。
• buildScriptName: "storybook:ui:build"：指定 Chromatic 调用的本地构建脚本名。这说明发布时并不强制使用默认的 build-storybook，而可以对接仓库自定义的 npm script，例如大型 monorepo 里用 Nx 编排的构建命令。
• storybookBaseDir: "code"：当 Storybook 位于仓库子目录（monorepo 场景）时，指定相对仓库根目录的 Storybook 所在目录。它揭示了 Chromatic Action 默认"在仓库根目录查找并构建"这一前提，如果你的 Storybook 不在根目录，就需要通过这类配置告知 Chromatic 正确的查找路径。
• onlyChanged: true 与 zip: true：前者关联 Chromatic 的增量构建能力（只对本次变化的 Story 触发测试），后者在上传前压缩产物。这些字段在 .github/workflows/chromatic.yml 中也可作为 Action 的输入参数传入，只是当前文档代码片段保留了最精简的必需项写法。

四、提交推送后的自动化效果与团队协作闭环

把 chromatic.yml 提交并推送到仓库后，自动化链路即刻生效：

1. 每次 push 触发构建：Chromatic Action 检出完整 git 历史 → 安装依赖 → 构建 Storybook → 上传快照到云端。
2. PR Checks 出现预览链接：当你在 GitHub 上打开 Pull Request，Chromatic 会作为一次检查项运行，并把本次构建对应的在线 Storybook 链接回填到 PR Checks 中。团队成员（开发、设计、产品等）无需安装本地环境或接触代码，点开链接即可查看最新 UI 效果并给出反馈。
3. 获得版本化历史：由于每一次构建都与具体 commit 绑定，发布后的 Storybook 天然拥有按提交粒度回溯的版本历史，在实现评审时可以直接对比不同分支/提交与历史版本之间的组件差异。

文档 publish-storybook.mdx 进一步指出，在 Chromatic 发布之上还可以启用 UI Review 功能，自动扫描 PR 中新增与更新的 Story，帮助团队快速识别变化点并就地评审。发布到 Chromatic 并非唯一出路——由于 Storybook 本质是静态站点，也可以托管到 GitHub Pages、Netlify、AWS S3 等任意静态托管；但组合（Composition）、嵌入（Embed）、历史版本化、安全鉴权等深度集成能力通常需要更贴合 Storybook API 的托管服务支持。这类讨论均可从 docs/sharing/ 目录下的文档进一步了解。

五、本地与 CI 行为核对：为什么"能跑通手动命令"仍可能失败

最后从工程经验角度给出几类高频问题排查思路，帮助读者核对配置是否与本地手动流程一致：

• 本地能 npx chromatic 通过、CI 却失败：优先确认 projectToken Secret 名称拼写与 YAML 中的引用完全一致，并检查是否误将 Token 写死在工作流文件中。Token 不匹配是 CI 独有的失败模式。
• 提示缺少 git 历史/无法计算基线：确认 actions/checkout 是否配置了 fetch-depth: 0。这是全篇最容易被删除但影响最隐蔽的一行——删除后视觉基线对比会失效。
• 包管理器不一致导致构建失败：文档示例以 yarn + cache: 'yarn' 为前提；若项目实际使用 npm/pnpm，需同步替换 setup-node 的 cache 字段与依赖安装命令，使 CI 与本地 lockfile 保持一致。
• Storybook 位于子目录（monorepo）：参考仓库 code/chromatic.config.json 中 storybookBaseDir 的用法，或在 Action 输入中显式指定 Storybook 目录与自定义构建脚本，避免 Chromatic 在错误的目录下找不到配置。
• 首次运行时构建号从 1 开始：手动命令输出的 Build 1 published. 代表首个基线建立成功。此后每次 PR 的视觉测试都会与该基线对比，出现任何未经确认的像素级变化都会在 Checks 中呈现，这正是自动化发布的额外价值——把发布管道与视觉回归测试合二为一。

结合官方文档 publish-storybook.mdx 与其配套代码片段 chromatic-github-action.md、chromatic-install.md，再对照仓库内真实的 chromatic.config.json，读者即可搭建一套"构建 → 发布 → PR 预览 → 视觉回归"全自动化的 UI 交付链路。