Create React App 中的组件独立开发：结合 Storybook 与 Styleguidist 实现组件状态可视化

一个 React 应用通常包含大量 UI 组件，而每个组件又往往存在多种状态。以文档中的例子来说，一个基础的按钮组件就可能同时具有：常规状态（带文本标签）、禁用（disabled）状态、加载（loading）状态。如果不借助专门工具，要逐一检视这些状态，开发者只能反复修改样例代码、启动整个应用再刷新页面，效率低下且容易遗漏边界状态。

Create React App（CRA）本身不内置任何组件独立开发工具，官方推荐的方案是在项目中引入第三方工具——Storybook 或 React Styleguidist，让组件脱离应用主流程、在隔离环境中独立开发和查看所有状态。本篇将完整介绍这两套工具在 CRA 项目中的接入方式、配套脚本配置，以及它们与 CRA 自带测试体系之间的关系。

为什么需要“组件独立开发”环境

在大型应用中，组件状态往往受数据、路由、权限等上游逻辑驱动。想单独观察一个组件的某种状态，传统做法是：

1. 修改 src 下的组件源码，强制其进入目标状态；
2. 启动开发服务器，打开对应页面，确认视觉效果；
3. 恢复代码，再切换到下一个状态……

这种方式的问题在于：组件的正确性验证被绑死在宿主应用上。组件库的维护者、UI 设计师、Code Review 参与者，都不得不启动完整应用（甚至后端服务）才能看到一个按钮的禁用态长什么样。

独立开发环境（Storybook / Styleguidist）解决的正是这个问题：为每个组件建立若干“场景（scenario/state）”，在独立界面中逐个浏览、交互，并支持把整个组件库部署为静态站点供团队评审——无需启动后端、无需在应用中创建账号。

Create React App 默认不包含此类工具：仓库证据

这一点可以从本仓库的实际内容得到印证：

• 构建与运行配置包 react-scripts/package.json 的依赖列表中，只有 webpack、babel、jest、eslint、sass-loader 等构建链依赖，没有任何 Storybook 或 Styleguidist 相关包，说明组件独立开发能力不属于 CRA 的默认运行链路；
• 新建项目的模板依赖清单 packages/cra-template/template.json 中声明的运行时依赖仅为 @testing-library/* 测试库与 web-vitals，即模板默认提供的是“测试能力”而非“组件工作台”；
• 默认模板中的组件 packages/cra-template/template/src/App.js 本身也是一个典型的“多状态载体”——它包含 logo 图片、文本、链接等多种元素，但其外观只能通过 npm start 启动应用后观察。

因此，官方文档给出的定位是明确的：这类工具是可选的第三方增强，按需引入，不影响 CRA 默认行为。

方案一：使用 Storybook 进行组件独立开发

Storybook 是一个面向 React UI 组件的开发环境，允许你浏览组件库、查看每个组件的不同状态，并交互式地开发和测试组件。

在 CRA 项目中初始化 Storybook

在应用目录下运行：

npx sb init

命令会检测项目使用的框架（对于 CRA 项目为 React + webpack 生态），随后交互式地提示你确认组件目录、Story 文件存放位置等选项。按照屏幕上的指引完成配置后，通常会得到类似以下的脚本：

"storybook": "start-storybook -p 6006",
"build-storybook": "build-storybook"

运行 npm run storybook 即可在本地 6006 端口打开 Storybook 界面。之后按照屏幕提示完成 Story 文件（通常为 *.stories.js）的编写即可。

适用前提：npx sb init 需要项目具备可用的 package.json 与 node_modules 环境，建议先确认 npm install 已成功完成。

与 Snapshot 测试的配合

Storybook 生态中还提供基于快照（Snapshot）的 UI 测试能力，即借助 addon/storyshots 为每个 Story 生成截图快照，纳入自动化回归。这与 CRA 自带的 Jest 体系是互补关系而非替代关系：

• 从 packages/react-scripts/scripts/utils/createJestConfig.js 可以看到，CRA 的 Jest 默认只匹配 src/**/__tests__/** 与 src/**/*.{spec,test}.js 两种测试文件，测试文件必须放在 src 目录下才不会被遗漏；
• 模板自带的组件测试 packages/cra-template/template/src/App.test.js 使用 @testing-library/react 渲染 <App /> 并断言 “learn react” 链接存在，属于行为断言；而 Storybook Story 描述的是视觉状态。两者结合，才能同时覆盖“组件做什么”与“组件长什么样”。

方案二：使用 React Styleguidist 生成组件风格指南

Styleguidist 结合了两种形态：一份风格指南（style guide，所有组件连同 props 文档和使用示例呈现在单个页面上），以及一个类似 Storybook 的组件隔离开发环境。与 Storybook 的差异在于：Styleguidist 的示例以 Markdown 编写，其中每段代码都会被渲染为可实时编辑的运行沙盒。

安装 Styleguidist

npm install --save react-styleguidist

或者使用 yarn：

yarn add react-styleguidist

配置 package.json 脚本

在 package.json 的 scripts 中追加两个条目：

   "scripts": {
+    "styleguide": "styleguidist server",
+    "styleguide:build": "styleguidist build",
     "start": "react-scripts start",

• styleguide server 启动本地开发服务器，支持热更新；
• styleguide build 将风格指南构建为一个静态站点，可部署到任意静态托管服务。

启动风格指南

npm run styleguide

首次运行后，按屏幕提示创建 Markdown 示例文件（通常位于 styleguide.config.js 指向的目录中，例如 components.md），即可在页面上看到组件列表、props 文档表格与可编辑示例。

# Button

一个基础按钮组件。

## 用法

```js
<Button onClick={fn}>点击我</Button>
<Button disabled>禁用状态</Button>
<Button loading>加载中</Button>

## 将组件工作台部署为静态站点

两个方案都支持构建产物：

| 工具 | 开发命令 | 构建命令 | 产物形态 |
| --- | --- | --- | --- |
| Storybook | `npm run storybook` | `npm run build-storybook` | 静态站点（Story 浏览界面） |
| Styleguidist | `npm run styleguide`（`styleguidist server`） | `npm run styleguide:build`（`styleguidist build`） | 静态站点（风格指南页面） |

部署为静态应用后，团队中的任何人都可以在线浏览、评审各个 UI 组件的状态，而**无需启动后端服务或在应用里创建账号**——这对于 UI 评审、设计走查、组件 API 文档查阅场景非常实用。

## 与 CRA 其他机制的关系小结

- **不与 `react-scripts` 构建链冲突**：Storybook 与 Styleguidist 拥有独立的启动/构建入口，与 `npm start` / `npm run build` 并行共存；
- **不进入应用运行时**：两者均为开发/构建期工具，构建出的 Story 页面与业务产物分离；
- **测试边界清晰**：CRA 的 Jest 只扫描 `src` 下的测试文件（见 [createJestConfig.js](https://gitcode.com/gh_mirrors/cr/create-react-app/blob/6254386531d263688ccfa542d0e628fbc0de0b28/packages/react-scripts/scripts/utils/createJestConfig.js?utm_source=gitcode_repo_files#L26-L40) 中 `roots` 与 `testMatch` 配置），因此组件的独立开发场景放在 Storybook/Styleguidist 中组织，而自动化断言仍保留在 `src` 下的 `*.test.js` 中，两者职责不重叠。

综上，在 Create React App 项目中，组件的“看得见、改得动、测得了”可以拆分为三层：用 Storybook 或 Styleguidist 实现状态的隔离开发与人眼评审，用其静态构建产物完成团队级共享，用 CRA 默认的 Jest + Testing Library 完成行为级自动化验证。三者按需组合，即可在不修改 CRA 配置、不 eject 的前提下，为组件开发建立完整的工作流。