HelloWorld 与 Storybook 配合教程

将 HelloWorld 与 Storybook 配合的核心就是：在一个前端项目里先做出可复用的 HelloWorld 组件，接着安装并初始化 Storybook，写好 stories 展示组件的不同状态，利用 controls 和 docs 丰富交互与文档，最后本地调试并构建部署。整个流程注重可视化开发、组件隔离与文档化，方便团队复用与迭代。

先说为什么要把 HelloWorld 放到 Storybook 里

简单来说，Storybook 是组件的“游乐场”。把一个最简单的 HelloWorld 组件放进去，有三个直观好处：

• 隔离开发：不需要页面和路由，专注组件本身。
• 可视化测试：快速查看不同 props、状态与样式。
• 自动文档：用 docs addon 可以把使用说明和示例直接生成文档。

把这第一步做好，以后做复杂组件时你会发现少走很多弯路。

准备工作：项目类型与环境

选用的框架会影响一些命令与默认配置。常见选择有 React、Vue、Angular、Svelte 等。这里用 React 举例（因为大多数人都更熟悉），但思路对其他框架也是一样的。

需要的工具

• Node.js（建议 LTS 版本）
• 包管理器：npm 或 yarn
• 脚手架：create-react-app 或 Vite（此处示例以 Vite 为主）

第一步：初始化项目

先创建一个项目，这一步无复杂概念，就是搭好“房子”的地基。

• 用 Vite：npm create vite@latest my-app — –template react
• 或用 CRA：npx create-react-app my-app

创建完成后，进入目录并安装依赖：

• cd my-app
• npm install 或 yarn

第二步：实现一个简单的 HelloWorld 组件

用最小的代码实现，让组件有可变的 props，方便在 Storybook 中演示。

示例文件结构（关键信息）：

示例组件（伪代码说明，不带具体代码块标签，概念为主）：

• 组件接收一个 name prop（字符串）和一个 size prop（small/medium/large）
• 根据 size 改变样式（例如字体大小或 padding）
• 默认 props：name 为 “World”，size 为 “medium”

你可以把它想成一个带可配置项的问候语组件，既有展示功能也能演示交互。

第三步：安装并初始化 Storybook

安装 Storybook 非常简单，官方提供初始化脚本，可以自动检测框架并生成基础配置。

• 运行：npx sb init（在项目根目录下）
• 它会安装所需依赖并在 package.json 增加 storybook 的运行脚本

初始化完成后，项目中会出现一个 .storybook 目录，里面含有 main.js、preview.js 等配置文件，负责告诉 Storybook 如何加载 stories、使用哪些 addon 以及如何处理样式与编译。

常见配置点（main.js）

• stories：指定 stories 的匹配规则，例如 “../src//*.stories.@(js|jsx|ts|tsx)”
• addons：controls、docs、a11y 等插件
• webpack/Vite 配置：根据项目需要扩展加载器或别名

第四步：编写 HelloWorld 的 stories

Stories 就是组件的不同状态“样本”。写 story 的核心思想很像写小型的 demo：每个 story 展示一个特定 prop 组合或交互条件。

• 创建文件：src/components/HelloWorld.stories.jsx
• 导出默认配置：title（在 Storybook 左侧目录的分组名称）、component（指向 HelloWorld）
• 导出若干命名的 story 函数/对象，如 Default、Large、WithName 等

写 story 时注意两种常见模式：

• Args 模式：把 props 放在 args 上，便于 controls 自动生成交互面板
• Template 模式：定义一个渲染函数，用 bind 或复制创建多个变体

示例说明（概念）

• Default：args = { name: ‘World’, size: ‘medium’ }
• Large：args = { name: ‘Friend’, size: ‘large’ }
• Interactive：可以通过 controls 改变 name 与 size，观察组件响应

第五步：运行 Storybook 并调试

初始化后，通常可以用以下命令启动本地 Storybook 服务：

• npm run storybook 或 yarn storybook

启动后打开本地地址（通常是 http://localhost:6006），在左侧选择 HelloWorld，就能看到你写的 story 列表。常见调试思路：

• 确认 stories 匹配规则是否包含你的文件名
• 检查控制台报错，调整 webpack 或 Vite 配置
• 如果样式丢失，查看 global css 是否在 preview.js 中引入

第六步：增强交互与文档（controls、args、docs）

Storybook 的强项之一是把组件的使用方式当成文档来呈现。几个关键点：

• Controls：通过 args 暴露 props，让非开发人员也能在 UI 面板调整值并即时看到结果。
• Docs：自动生成组件 API 表格、示例代码块以及用法说明。
• Actions：用于捕捉事件回调（如 onClick），便于验证交互。

一句话：把组件的投入使用门槛降到最低，同时把行为记录成文档。

第七步：测试、截图与可访问性

Storybook 支持与测试工具集成，常见做法：

• 用 Storybook 的 snapshot 测试（结合 Jest 或 Chromatic）定期校验 UI 回归
• 利用 a11y addon 检查无障碍问题
• 借助 visual regression 服务（例如 Chromatic）做视觉回归监控

这些在团队协作尤其有用，可以把组件变更的风险降到最低。

第八步：构建并部署 Storybook

当你想把 Storybook 作为静态文档发布时，执行构建命令生成静态文件：

• npm run build-storybook（或相应脚本）

构建产物通常位于 storybook-static 文件夹，之后可以部署到任何静态站点托管服务或集成到 CI/CD 流程：

• 在 CI 中运行构建并把静态文件推送到托管平台
• 也可以在 PR 合并时触发 Chromatic 用于可视化审查

常见问题与排错思路

• Story 不显示：检查文件匹配 pattern，文件名是否为 *.stories.*
• 样式不生效：确认全局样式在 .storybook/preview.js 中引入，或检查 CSS Modules/Styled Components 的处理
• 构建失败：查看错误堆栈，是否有不兼容的 loader 或插件，必要时在 main.js 中自定义 webpack/Vite 配置
• 第三方库无法渲染：某些库在 SSR 或 Storybook 的环境中行为不同，尝试 mock 或延迟加载

示例项目结构参考表

一些实践建议（边做边调优的心态）

• 刚开始先把组件做小：单一职责，便于写故事与测试。
• 用 args 模式让 story 更具可组合性，减少重复代码。
• 把常用装饰器放到 preview.js，中性化外部环境（如主题、字体、容器大小）。
• 频繁把 story 当成 demo 来用，团队成员不熟悉组件时直接给链接看。

最后，几点容易忽略的细节

Storybook 本质上是把组件的开发、测试与文档化流程串联起来。实际操作中经常会有小摩擦：例如依赖版本冲突、样式优先级问题、或是组件与后端 API 绑定导致无法在隔离环境运行。解决思路通常是把外部依赖 mock 掉，或者在 story 里提供假数据，再在集成测试里恢复真实数据流。按这个节奏，你会越来越得心应手，HelloWorld 只是个起点而已，我在写这里的时候就想到很多团队在初期忽视了文档化，后来会后悔没有早点把 story 做好。