React 用 Storybook 搭建组件文档与可视化测试：从零到可交互文档站

为什么需要 Storybook

组件越写越多，真正麻烦的不是写，而是「找不到、看不懂、不敢改」。把 Button、Modal 这类组件塞进业务页面里调试，每次都要走完整链路才能看到效果。Storybook 把组件单独隔离出来，给每个状态一个独立的「故事」，既是文档，也是可视化测试入口。

在 Vite + React 项目里接入

用官方初始化命令即可，它会根据项目类型自动写入 .storybook 配置与示例：

npx storybook@latest init --builder vite

生成的 .storybook/main.ts 决定故事文件的位置与渲染框架：

import type { StorybookConfig } from "@storybook/react-vite";

const config: StorybookConfig = {
  stories: ["../src/**/*.stories.@(ts|tsx)"],
  addons: ["@storybook/addon-essentials"],
  framework: {
    name: "@storybook/react-vite",
    options: {},
  },
};

export default config;

写一个 CSF 故事

Component Story Format（CSF 3.0）用默认导出描述组件元信息，命名导出描述每个故事：

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

const meta: Meta = {
  title: "UI/Button",
  component: Button,
  args: {
    label: "提交",
    loading: false,
  },
};

export default meta;

type Story = StoryObj;

export const Primary: Story = {
  args: { variant: "primary" },
};

export const Loading: Story = {
  args: { variant: "primary", loading: true },
};

用 args 与 controls 做交互

args 是组件的入参，Storybook 的 controls 插件会把它们自动渲染成可调面板。改一个值，组件实时重渲染，不用改代码就能覆盖各种状态。

用 play 函数写组件交互测试

story 里的 play 函数能在渲染后自动操作组件，配合 @storybook/test 的 expect 做可视化断言：

import { expect, userEvent, within } from "@storybook/test";

export const ClickFlow: Story = {
  args: { label: "计数" },
  play: async ({ canvasElement }) => {
    const canvas = within(canvasElement);
    const button = canvas.getByRole("button");
    await userEvent.click(button);
    await expect(button).toHaveTextContent("计数 1");
  },
};

跑起来与交付

本地用 npm run storybook 起开发服务；要交付静态文档站就构建成静态文件，挂到内网或对象存储：

npm run build-storybook
# 产物在 storybook-static/，直接当作静态站点部署

把组件故事纳入流水线，每次提交自动跑 play 测试，组件库的回归风险会被压到很低。