发布 Storybook

观看视频教程

团队会在网上发布 Storybook，以便审查和协作处理进行中的工作。这使得开发人员、设计师、产品经理和其他利益相关者可以在不接触代码或不需要本地开发环境的情况下，检查 UI 是否正确显示。

构建 Storybook 作为静态 Web 应用程序

首先，我们需要将 Storybook 构建为一个静态 Web 应用程序。该功能已内置，并为大多数支持的框架进行了预配置。在项目根目录下运行以下命令：

npm run build-storybook

您可以提供其他标志来自定义命令。在此处阅读有关标志选项的更多信息。

Storybook 将创建一个静态 Web 应用程序，可由任何 Web 服务器提供。通过运行以下命令在本地预览它：

npx http-server ./path/to/build

自定义构建以提高性能

默认情况下，Storybook 的生产构建会将所有故事和文档封装到生产包中。这对于小型项目非常理想，但对于大型项目或当优先级是缩短构建时间时（例如，测试、CI/CD），可能会导致性能问题。如果需要，您可以使用 `main.js|ts` 配置文件中的 test 选项来自定义生产构建，并调整构建脚本以使用 --test 标志启用优化。

npm run build-storybook -- --test

为旧版浏览器构建 Storybook

Storybook 应用的用户界面支持现代浏览器。如果您需要在旧的、不受支持的浏览器中运行该应用程序，可以使用 --preview-only CLI 标志以“仅预览”模式构建 Storybook。这将跳过构建 Storybook 管理器（环绕您故事的用户界面），只构建预览（包含您故事的 iframe）。这使得您的 Storybook 构建器及其配置全权负责支持哪些浏览器。

处于“仅预览”模式时，正常的入口点 `/index.html` 将导致 404，因为客户端路由不可用。要解决此问题，请从 `/iframe.html` 路由开始，并将 `?navigator=true` 查询参数添加到 URL。这将渲染一个基本的、仅 HTML 的侧边栏，以便您可以导航到您的故事。例如，您可以访问预览 https://:6006/iframe.html?navigator=true（您可能需要更新端口号）。

这适用于 build（用于发布）和 dev（用于本地开发）命令。

使用 Chromatic 发布 Storybook

将 Storybook 构建为静态 Web 应用程序后，您可以将其发布到您的 Web 主机。我们推荐 Chromatic，这是一个免费的、专为 Storybook 设计的发布服务，可在云中安全地记录、版本化和索引您的 UI 组件。

Storybook publishing workflow

要开始，请使用您的 GitHub、GitLab、Bitbucket 或电子邮件进行注册，并为您的项目生成一个唯一的*项目令牌*。

接下来，从 npm 安装 Chromatic CLI 包

npm install chromatic --save-dev

在软件包安装完成后运行以下命令。请确保将 `your-project-token` 替换为您自己的项目令牌。

npx chromatic --project-token=<your-project-token>

当 Chromatic 完成后，您应该已成功部署了您的 Storybook。通过点击提供的链接（例如，https://random-uuid.chromatic.com）进行预览。

Build 1 published.
 
View it online at https://www.chromatic.com/build?appId=...&number=1.

Chromatic publish build

设置 CI 以自动发布

配置您的 CI 环境以发布您的 Storybook，并在每次将代码推送到存储库时运行 Chromatic。让我们看看如何使用 GitHub Actions 进行设置。

在您的项目根目录下，在 `.github/workflows` 目录中添加一个名为 `chromatic.yml` 的新文件

.github/workflows/chromatic.yml

# 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@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          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 }}

Secret 是 GitHub 提供的安全环境变量，因此您无需硬编码您的 `project-token`。阅读官方文档以了解如何配置它们。

提交并推送文件。恭喜，您已成功自动化发布您的 Storybook。现在，每当您打开 PR 时，都将在 PR 检查中获得一个指向已发布 Storybook 的便捷链接。

PR check publish

与团队审查

将 Storybook 作为开发流程的一部分发布，可以轻松快速地收集团队反馈。

一种常见的请求审查方法是将已发布的 Storybook 的链接粘贴到 Pull Request 或 Slack 中。

如果您将 Storybook 发布到 Chromatic，您可以使用 UI Review 功能来自动扫描 PR 中的新故事和更新故事。这使得识别更改并提供反馈变得容易。

UI review in Chromatic

版本控制和历史记录

发布 Storybook 时，您还可以获得组件历史记录和版本控制，直至提交。这在实现审查期间非常有用，可以比较分支/提交与过去版本的组件。

Library history in Chromatic

将 Storybook 发布到其他服务

由于 Storybook 构建为静态 Web 应用程序，您也可以将其发布到任何 Web 主机，包括 GitHub Pages、Netlify、AWS S3 等。但是，诸如 Composition、embedding stories、历史记录、版本控制和资产等功能可能需要与 Storybook API 更紧密的集成和安全身份验证。如果您想了解更多关于标头的信息，可以参考迁移指南。此外，如果您想了解组件发布协议（CPP），可以在下面找到更多信息。

GitHub Pages

要在 GitHub Pages 上部署 Storybook，请使用社区构建的 Deploy Storybook to GitHub Pages Action。要启用它，请在您的 `.github/workflows` 目录中创建一个名为 `deploy-github-pages.yml` 的新工作流文件，其中包含以下内容

.github/workflows/deploy-github-pages.yml

# Workflow name
name: Build and Publish Storybook to GitHub Pages
 
on:
  # Event for the workflow to run on
  push:
    branches:
      - 'your-branch-name' # Replace with the branch you want to deploy from
 
permissions:
  contents: read
  pages: write
  id-token: write
 
# List of jobs
jobs:
  deploy:
    runs-on: ubuntu-latest
    # Job steps
    steps:
      # Manual Checkout
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      # Set up Node
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      #👇 Add Storybook build and deploy to GitHub Pages as a step in the workflow
      - uses: bitovi/github-actions-storybook-to-github-pages@v1.0.3
        with:
          install_command: yarn install # default: npm ci
          build_command: yarn build-storybook # default: npm run build-storybook
          path: storybook-static # default: dist/storybook
          checkout: false # default: true

GitHub Pages Action 需要额外的配置选项来定制部署过程。有关更多信息，请参阅官方文档。

组件发布协议 (CPP)

Storybook 可以与托管已发布 Storybook 的服务进行通信。这支持诸如 Composition 等功能。我们将服务按对“组件发布协议” (CPP) 的合规性进行分类，并在 Storybook 中提供不同级别的支持。

CPP 级别 1

此级别的服务支持已发布的 Storybook，并提供以下功能：

版本化端点，URL 根据 version=x.y.z 查询参数（其中 x.y.z 是软件包的发布版本）解析到不同的已发布 Storybook。
支持 `/index.json`（以前为 `/stories.json`）端点，该端点返回故事及其元数据的列表。
支持 `/metadata.json` 和 `releases` 字段。

示例：Chromatic

<meta name="description" content="Components for my awesome project" key="desc" />

阻止您的 Storybook 被抓取

您可以通过在配置目录中的 `manager-head.html` 文件中添加以下内容，来防止您的已发布 Storybook 出现在搜索引擎结果中，其中包含一个 noindex 元标记：

.storybook/manager-head.html

<meta name="robots" content="noindex" />