组件库提速：Storybook + Chromatic + Visual Test 实战

组件库开发如果没有文档、测试、变更对比，很容易出事故。Storybook + Chromatic（或 Percy）+ 可视化回归测试，可以让组件开发、UI 审核、测试、发布形成闭环。今天我们搭建一条"组件库流水线"：开发在 Storybook，自动生成文档，PR 自动跑视觉回归，产出 Demo 链接给设计/产品审核，效率直接提升。

🎯 目标

组件开发全在 Storybook Story 中完成。
自动部署到 Chromatic，生成在线文档和对比截图。
PR 中自动执行视觉回归，避免 UI 意外变化。

🧱 Storybook 初始化

bash 复制代码

npx storybook@latest init --builder @storybook/builder-vite

生成目录：

复制代码

.storybook/
stories/

.storybook/main.ts：

ts 复制代码

export default {
  stories: ['../src/**/*.stories.@(ts|tsx|mdx)'],
  addons: [
    '@storybook/addon-essentials',
    '@storybook/addon-interactions',
  ],
  framework: {
    name: '@storybook/react-vite',
    options: {},
  },
};

🧩 编写 Story

tsx 复制代码

import type { Meta, StoryObj } from '@storybook/react';
import { Button } from './Button';

type Story = StoryObj<typeof Button>;

const meta: Meta<typeof Button> = {
  title: 'Atoms/Button',
  component: Button,
  argTypes: {
    variant: { control: 'select', options: ['primary', 'secondary'] },
  },
};
export default meta;

export const Primary: Story = {
  args: {
    children: '点击我',
    variant: 'primary',
  },
};

Story 即文档 + Demo + 用例。

🚀 Chromatic 集成

bash 复制代码

pnpm install -D chromatic

package.json：

json 复制代码

{
  "scripts": {
    "storybook": "storybook dev -p 6006",
    "build-storybook": "storybook build",
    "chromatic": "chromatic --project-token=$CHROMATIC_TOKEN"
  }
}

在 CI 中执行 pnpm chromatic，自动上传 Storybook。
PR 中生成预览链接 + 视觉对比。

🧪 可视化回归

Chromatic 自动对比当前 Story 与上一次基准图。
设计/开发在浏览器中审核变化，批准或拒绝。
无额外脚本，自带 UI。

⚙️ 与测试结合

使用 @storybook/testing-react 把 Story 作为测试用例：

ts 复制代码

import { render } from '@testing-library/react';
import { composeStory } from '@storybook/testing-react';
import Meta, { Primary } from './Button.stories';

const PrimaryStory = composeStory(Primary, Meta);

test('按钮点击', () => {
  const { getByText } = render(<PrimaryStory />);
  expect(getByText('点击我')).toBeInTheDocument();
});

Story 一处编写，多处复用。

🧯 常见坑

问题	现象	解决
Storybook 构建慢	组件多	使用 Vite Builder、按需加载
Chromatic 限制	免费版并发低	提前排队、升级套餐或使用 Percy
Story 未及时更新	同步困难	把 Story 写成组件开发必经步骤，PR 模板提醒
可视化误报	动态数据导致波动	使用固定数据、Mock Date/Math.random

🏁 小练习

给团队的组件库接入 Storybook 和 Chromatic，体验审批流程。
使用 Story 生成自动化测试，提高覆盖率。