⚡ 零配置组件开发：Storybook CLI + Vite 自动化工作流指南

本指南将展示如何使用 Storybook CLI 实现一键配置，结合 Vite 构建现代化组件库，实现自动文档生成、交互测试和覆盖率优化，显著降低首次使用门槛。

环境初始化：Storybook CLI 一键配置

1. 创建 Vite 项目（React + TS 示例）

bash 复制代码

npm create vite@latest my-storybook -- --template react-ts
cd my-storybook

2. 使用 Storybook CLI 自动配置

bash 复制代码

npx storybook@latest init

CLI 自动完成以下操作：

✅ 安装所有必要依赖 (@storybook/react-vite, @storybook/addons 等)
✅ 创建默认配置文件 (.storybook/main.ts, .storybook/preview.ts)
✅ 添加示例组件和 Stories
✅ 配置 Vite 集成
✅ 添加 NPM 脚本到 package.json

3. 验证安装

bash 复制代码

npm run storybook

访问 http://localhost:6006 查看运行中的 Storybook 和示例组件。

CLI 生成的配置文件解析

1. 核心配置文件

Storybook CLI 自动生成以下配置文件：

.storybook/main.ts：

typescript 复制代码

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

const config: StorybookConfig = {
  stories: ['../src/**/*.stories.@(js|jsx|ts|tsx)'],
  addons: [
    '@storybook/addon-links',
    '@storybook/addon-essentials', // 包含 Controls/Docs/Actions 等核心功能
    '@storybook/addon-interactions', // 交互测试
    '@storybook/addon-a11y', // 可访问性测试
  ],
  framework: {
    name: '@storybook/react-vite',
    options: {},
  },
  docs: {
    autodocs: 'tag', // 自动为标记组件生成文档
  },
};

export default config;

.storybook/preview.ts：

typescript 复制代码

import type { Preview } from '@storybook/react';
import '../src/index.css'; // 自动导入全局样式

const preview: Preview = {
  parameters: {
    actions: { argTypesRegex: '^on[A-Z].*' },
    controls: {
      matchers: {
        color: /(background|color)$/i,
        date: /Date$/,
      },
    },
  },
};

export default preview;

自动文档生成实战

1. 创建带 JSDoc 的组件

src/components/Button.tsx：

tsx 复制代码

interface ButtonProps {
  /**
   * 按钮样式类型
   * @default 'primary'
   */
  variant?: 'primary' | 'secondary';
  children: React.ReactNode;
}

/**
 * 通用按钮组件
 * 
 * @example
 * <Button variant="primary">点击我</Button>
 */
export const Button = ({ variant = 'primary', children }: ButtonProps) => {
  return <button className={`btn-${variant}`}>{children}</button>;
};

2. CLI 自动配置的文档效果

在 Story 文件中无需额外配置：

tsx 复制代码

// src/stories/Button.stories.tsx
import type { Meta } from '@storybook/react';
import { Button } from '../components/Button';

const meta: Meta<typeof Button> = {
  title: 'Components/Button',
  component: Button,
  tags: ['autodocs'], // CLI 已默认添加
};

export default meta;

Storybook 将自动生成包含以下内容的文档：

从 JSDoc 提取的描述和示例
Props 类型表格
交互式控件面板

测试全流程配置

1. 添加测试相关插件

使用 CLI 一键安装测试插件：

bash 复制代码

npx storybook add @storybook/addon-coverage

2. 配置覆盖率

.storybook/main.ts 添加：

typescript 复制代码

const config: StorybookConfig = {
  // ... 其他配置
  addons: [
    // ... 其他插件
    {
      name: '@storybook/addon-coverage',
      options: {
        istanbul: {
          include: ['**/src/components/**/*.tsx'], // 指定采集范围
        },
      },
    },
  ],
};

3. 编写交互测试

Button.stories.tsx：

tsx 复制代码

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

export const ClickExample: Story = {
  args: { children: '点击测试' },
  play: async ({ canvasElement }) => {
    const canvas = within(canvasElement);
    const button = canvas.getByRole('button');
    await userEvent.click(button);
    await expect(button).toHaveStyle('background-color: #1ea7fd');
  },
};

测试覆盖率可视化

1. 启动覆盖率采集

bash 复制代码

npm run storybook -- --coverage

2. 查看覆盖率报告

在 Storybook 界面右下角点击覆盖率图标：

graph LR A[覆盖率面板] --> B[文件列表] A --> C[行覆盖率] A --> D[分支覆盖率] A --> E[函数覆盖率]

3. 生成详细报告

在 package.json 添加脚本：

json 复制代码

"scripts": {
  "test:coverage": "storybook test --coverage --json > coverage.json"
}

自定义文档进阶

1. 创建 MDX 文档

src/components/Button.docs.mdx：

mdx 复制代码

import { Meta, Story } from '@storybook/blocks';
import * as ButtonStories from './Button.stories';

<Meta of={ButtonStories} />

# 按钮组件规范

## 设计指南
<Story of={ButtonStories.Primary} />

## 使用说明
```jsx live
<Button variant="primary">实际应用示例</Button>

部署与协作

1. 构建静态站点

bash 复制代码

npm run build-storybook

2. 一键部署到 Chromatic

bash 复制代码

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

CLI 常用命令速查

命令	功能
`npx storybook init`	初始化 Storybook
`npx storybook add <addon-name>`	添加官方插件
`npx storybook upgrade`	升级 Storybook
`npx storybook build`	构建静态站点
`npx storybook test`	运行测试
`npx storybook --coverage`	启用覆盖率采集

常见问题解决

问题	解决方案
CLI 安装失败	使用 `npm init` 创建项目避免权限问题
文档不生成	确保组件 Story 包含 `tags: ['autodocs']`
覆盖率数据为空	检查 `include` 路径是否匹配组件文件
交互测试报错	在 `play` 函数中添加 `await new Promise(r => setTimeout(r, 100))` 等待渲染

最佳实践工作流

1. 组件开发流程

graph TD A[创建组件] --> B[添加 Story] B --> C[编写交互测试] C --> D[查看文档效果] D --> E[提交代码]

2. CI/CD 集成

.github/workflows/storybook.yml：

yaml 复制代码

name: Storybook CI

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - run: npm ci
      - run: npm run build-storybook
      - run: npx chromatic --project-token=${{ secrets.CHROMATIC_TOKEN }}
      
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - run: npm ci
      - run: npm run test:coverage
      - uses: codecov/codecov-action@v3
        with:
          file: coverage.json

总结：CLI 驱动的开发优势

通过 Storybook CLI 可实现：

⚡ 5 分钟完成配置：从安装到运行一条龙
📦 零配置最佳实践：自动集成 Vite 和测试工具
🔄 持续更新保障 ：通过 storybook upgrade 保持最新版本
🧪 测试覆盖可视化：一键启用覆盖率报告

下一步行动：

运行 npx storybook@latest init 开始您的组件之旅

添加 JSDoc 注释查看自动文档效果

使用 npm run storybook -- --coverage 查看测试覆盖率

官方资源：