从0到1上手Storybook：环境搭建到第一个组件
10分钟搞定环境：比搭Vue项目还简单
你可能会想：”工具配置这种事最头疼了，万一搞半天跑不起来怎么办？” 其实Storybook这两年已经把配置简化到像搭脚手架一样简单。我去年带实习生做项目时，发现他们一开始总觉得这工具”高级”，其实只要跟着这几步走，10分钟就能跑起来——比你装个复杂点的npm包还快。
首先打开你的前端项目（不管是React、Vue还是Angular，Storybook都支持），在终端里输入对应框架的安装命令。不同框架的命令稍微有点区别，我整理了个表格，你对着抄就行：
| 框架类型 | 安装命令 | 配置文件位置 |
|---|---|---|
| React | npx storybook@latest init | .storybook/main.js |
| Vue 3 | npx storybook@latest init | .storybook/main.js |
| Angular | npx storybook@latest init | .storybook/main.ts |
> 表格说明：不管用什么框架，核心命令都是npx storybook@latest init，它会自动检测你的项目类型并安装对应依赖，比手动配webpack省心多了。
跑完命令后，终端会提示你运行npm run storybook，回车后稍等几秒，浏览器会自动弹出一个页面——这就是Storybook的管理界面了！你会看到默认带了几个示例组件，比如Button、Header，这些就是”故事(Story)”——Storybook里把每个组件的使用场景叫做一个”故事”，是不是比”组件示例”好记多了？
写第一个组件故事：像写作文一样简单
别被”故事”这个词吓到，其实写组件故事比写业务逻辑简单多了。我举个例子：假设你项目里有个PrimaryButton组件，有三种状态：默认、禁用、加载中。以前你可能要在页面里写三个按钮才能看到效果，现在用Storybook，一个文件就能搞定所有状态。
先在src/components目录下新建PrimaryButton.stories.js（React/Vue）或.stories.ts（TypeScript），文件名固定是[组件名].stories.[js/ts]。然后复制这段代码（以React为例）：
import PrimaryButton from './PrimaryButton';
export default {
title: 'Components/PrimaryButton', // 故事在左侧导航的位置
component: PrimaryButton, // 要展示的组件
argTypes: {
onClick: { action: 'clicked' }, // 点击事件会在控制台显示
disabled: { control: 'boolean' }, // 右侧控制面板会出现开关
isLoading: { control: 'boolean' }, // 右侧控制面板会出现开关
},
};
// 默认状态故事
export const Default = (args) => 点击我;
Default.args = {
disabled: false,
isLoading: false,
};
// 禁用状态故事
export const Disabled = (args) => 禁用按钮;
Disabled.args = {
disabled: true,
isLoading: false,
};
// 加载中状态故事
export const Loading = (args) => 加载中...;
Loading.args = {
disabled: true,
isLoading: true,
};
保存后回到Storybook界面，左侧导航会多出”Components”分类，点进去就能看到你的PrimaryButton有三个故事。右侧还有控制面板，你可以勾选”disabled”或”isLoading”，实时看到组件变化——就像给组件装了个”调试遥控器”。
我第一次写故事时，纠结了半天title怎么命名，后来发现按”功能模块/组件名”的格式最清晰，比如”Form/Input”、”Layout/Header”，团队协作时大家一眼就知道组件属于哪个模块。Storybook官方文档里也推荐这种命名方式，你可以参考Storybook官方指南（已添加nofollow）里的最佳实践。
Storybook进阶技巧：组件文档、测试与团队协作
自动生成组件文档：从此告别”文档比代码还难写”
你是不是也经历过”写文档比写代码还费时间”？以前团队用Confluence写组件文档，每次改组件属性，都得手动更新文档里的表格，结果经常出现”代码里是maxLength，文档里写成max-len“的低级错误。自从用了Storybook的Docs插件，这些问题全解决了——文档直接从代码注释生成，永远和代码保持同步。
怎么让文档自动生成呢？其实很简单，只要在组件代码里写标准的JSDoc注释就行。比如给PrimaryButton加注释：
/
项目主要按钮组件，用于关键操作如"提交""确认"
@param {boolean} disabled
是否禁用按钮
@param {boolean} isLoading 是否显示加载状态
@param {() => void} onClick
点击事件回调
/
const PrimaryButton = ({ disabled, isLoading, onClick, children }) => {
// 组件逻辑...
};
然后在故事文件的默认导出里加一句docs: { page: DocsPage }，引入Storybook自带的DocsPage组件：
import { DocsPage } from '@storybook/addon-docs';
export default {
title: 'Components/PrimaryButton',
component: PrimaryButton,
argTypes: { / ... / },
docs: { page: DocsPage }, // 启用自动文档页面
};
刷新Storybook，点击导航栏的”Docs”标签，你会看到自动生成的文档页面：顶部是组件说明，中间是参数表格（把JSDoc注释自动转成表格），下面是各个故事的预览——连示例代码都帮你格式化好了！我司UI设计师现在都直接看Storybook文档，再也不用追着我问”这个按钮的hover色值是多少”了。
组件测试：让按钮不再”偷偷坏掉”
你有没有遇到过这种坑：改了一个组件的样式，结果另一个页面里的按钮突然错位了？这就是组件没有测试的锅。Storybook不仅能展示组件，还能帮你自动测试组件是否”坏掉”。我推荐两个工具：Storybook Test Runner和Chromatic。
Storybook Test Runner是官方出的测试工具，能自动测试所有故事是否能正常渲染。安装命令很简单：
npm install @storybook/test-runner save-dev然后在package.json里加个脚本：
"scripts": {
"test-storybook": "test-storybook"
}
运行npm run test-storybook，它会打开浏览器（你看不到界面，是无头模式），逐个运行所有故事，确保没有报错。我之前在项目里加了这个脚本后，每次提交代码前跑一遍，发现了好几个”看起来正常，其实控制台报错”的组件问题。
如果你想要更高级的视觉回归测试（比如检测像素级的样式变化），可以试试Chromatic——Storybook团队开发的在线工具，免费版足够小团队用。注册后按提示把项目接入，每次提交代码会自动截图对比，有样式变化会发邮件提醒你确认。我去年做一个电商项目，用Chromatic抓到过”按钮文字在Safari里偏移1px”的问题，要知道这种细节在开发环境根本发现不了！
团队协作：让组件成为”共享积木”
Storybook最香的地方不是”一个人用得爽”，而是”整个团队都能用”。我分享三个让团队协作效率翻倍的技巧：
npm run build-storybook生成静态文件，部署到Netlify或公司服务器，团队成员不用拉代码就能看最新组件。我们团队把文档地址贴在Slack频道，新人入职第一天就能自己查组件用法，省了我不少培训时间。parameters加说明文字，比如：Default.parameters = {
docs: {
storyDescription: '默认状态按钮，用于主要操作， 一个页面最多出现1-2个',
},
};
这样别人用组件时就知道”什么时候该用这个组件”，而不只是”怎么用”。
最后给你个小 刚开始用Storybook别贪多，先把项目里复用率最高的5个组件（比如按钮、输入框、卡片、弹窗、下拉菜单）整理成故事，跑通文档和测试流程，再慢慢扩展。你会发现，以前花在”找组件、问用法、改bug”上的时间，至少能省下来一半——这些时间用来摸鱼不香吗？
对了，如果你按这些步骤搭好了Storybook，记得回来告诉我：你项目里第一个”故事”是哪个组件？有没有遇到什么坑？咱们评论区接着聊！
你是不是遇到过这种情况：辛辛苦苦写好了组件故事，打开Docs标签页一看，组件预览倒是有了，可旁边本该列出属性说明的参数表格却空空如也？别急，这事儿我之前帮同事排查过好几次，其实就两个关键点没做到位，你对照着检查一下准能解决。
先说第一个关键点，就是组件代码里的JSDoc注释。很多人觉得“注释嘛，随便写写意思到了就行”，但Storybook生成参数表格可是认“规矩”的——你得用标准的@param标签把每个属性都说明白，包括类型、用途，最好再举个例子。比如你写了个Input组件，有个maxLength属性，正确的注释得是这样：/ @param {number} maxLength
再来说第二个关键点，故事文件里的DocsPage配置。你是不是以为只要装了@storybook/addon-docs插件就万事大吉了？其实还得在故事的默认导出里明确告诉Storybook“我要用文档页面”。具体来说，就是在export default那个对象里加一句docs: { page: DocsPage }，而且别忘了从@storybook/addon-docs里把DocsPage组件引进来。我见过有人漏了这一步，结果Storybook侧边栏根本没有Docs标签页，还以为是插件没装好，折腾半天其实就是少了几行配置。另外还有个小细节，要是你用的是TypeScript，最好把组件的Props类型定义清楚，Storybook会结合类型和JSDoc注释一起生成表格，参数说明会更准确——比如类型是string还是number，必填还是可选，这些都会在表格里标得明明白白。
所以下次遇到参数表格没生成的情况，先别急着重启项目或者重装依赖，按这两步检查：组件代码里的JSDoc注释是不是规范完整，故事文件的默认导出有没有配置DocsPage。这俩都搞定了，再刷新Storybook看看，参数表格保准乖乖出来，连每个属性的默认值、示例用法都给你列得清清楚楚，团队同事看文档时再也不用猜“这个属性到底是干嘛的”了。
Storybook支持哪些前端框架？
Storybook对主流前端框架都有良好支持，包括React、Vue 2/3、Angular、Svelte、Preact等，甚至支持原生HTML/CSS/JS项目。安装时它会自动检测你的项目类型并安装对应依赖，无需手动配置框架适配。具体支持的框架列表可以查看Storybook官方框架文档。
安装Storybook时提示“依赖冲突”或“安装失败”怎么办？
遇到安装问题时，可以先检查Node.js版本是否符合要求（ 使用Node.js 14.0.0及以上版本），然后尝试删除项目的node_modules文件夹和package-lock.json（或yarn.lock），重新运行npm install安装依赖，最后再执行npx storybook@latest init。如果是网络问题，可切换npm镜像源（如使用cnpm或npm config set registry https://registry.npm.taobao.org）后重试。
故事文件（.stories.js/ts）必须放在组件同一目录吗？
不一定必须，但推荐将故事文件与组件放在同一目录（如src/components/Button/Button.stories.js），这样查找组件和对应故事更方便。如果需要集中管理，也可以在src下创建.stories目录统一存放，但需在.storybook/main.js的stories配置中指定路径，例如：stories: [‘../src/*/.stories.@(js|jsx|ts|tsx)’]，确保Storybook能正确识别。
为什么我的组件文档没有自动生成参数表格？
自动生成参数表格需要两个条件：一是组件代码中添加了规范的JSDoc注释（包含@param说明每个属性），二是在故事文件的默认导出中配置了docs: { page: DocsPage }（引入@storybook/addon-docs的DocsPage组件）。如果缺少JSDoc注释，文档只会显示组件预览而没有参数说明；如果未配置DocsPage，可能无法切换到文档标签页。
如何让团队成员随时查看最新的Storybook文档？
可以通过以下步骤共享：
