storybook-rsbuild

Storybook Rsbuild

目标

在 Rsbuild 上设置 Storybook，或将现有 Storybook 迁移到 Rsbuild。有关版本兼容性、软件包名称、安装命令和配置转换模式的事实性映射，请查阅上游文档 storybook.rsbuild.rs。本技能是一个操作路由器和行为检查清单，不会重复文档内容。

原则（必须遵循）

1. 以上游文档为唯一事实来源。 获取相关的 storybook.rsbuild.rs 页面，查询版本表、安装命令和配置转换模式。不要根据训练记忆推断版本固定值或软件包名称——生态系统的变化速度快于模型的既有认知。

2. 根据框架指南中的 Requirements 表固定版本。 每个框架指南页面（例如 https://storybook.rsbuild.rs/guide/framework/react）都有一个 Requirements 部分，其中列出规范的兼容版本范围——这是确定版本固定值的权威来源。对于全新设置，请安装最新的稳定版 storybook 主版本，以及匹配的 storybook-rsbuild 主版本。不要根据其他代码片段中的版本号固定版本；只有文档才是权威来源。

3. 直接声明 @rsbuild/core。 storybook-<framework>-rsbuild 将 @rsbuild/core 列为对等依赖，但你仍必须将 @rsbuild/core 添加到项目自身的 devDependencies 中，以确保版本固定和锁文件审计明确无误，并防止未来框架软件包版本移除该对等依赖后悄悄导致构建失败。

4. 迁移是一项包含两个有序阶段的任务——两者都必须完成。 阶段 A：安装新的框架软件包并更新配置；保留旧框架软件包、旧构建器软件包以及旧的 webpackFinal / viteFinal 块，以便 验证 时可以回滚。阶段 B：验证通过后，立即在同一任务中移除旧框架软件包（例如 @storybook/react-webpack5、@storybook/vue3-vite）、旧构建器软件包（例如 @storybook/builder-webpack5、@storybook/builder-vite），以及旧的 webpackFinal / viteFinal 块。迁移结束时，若 package.json 仍包含两个构建器的框架软件包，则迁移尚未完成——在本技能的评估中，保留这些软件包是最常见的隐性回归。阶段 A 本身不能作为有效的停止点；如果你执行了验证，也必须执行清理。

5. 保留插件；绝不能悄悄移除。 迁移时，仅适用于 webpack 的插件（例如 @storybook/addon-styling-webpack）必须通过 webpackAddons 传递（以便由上游自动转换处理），或替换为等效的 Rsbuild 原生流水线（@rsbuild/plugin-postcss、tools.postcss 等）。如果移除了样式插件，虽然 storybook build 通过，但故事树的显示效果出现问题，这仍然属于回归。

6. 限定操作范围。 在单体仓库中，只修改承载故事的那个软件包。除非迁移确有必要，否则不要编辑业务源文件。

步骤 1 — 检测场景

读取 package.json 和项目结构，确定现有 Storybook 状态：

1. 检查 .storybook/ 目录（在单体仓库中，同时检查根目录和各软件包目录）
2. 检查 package.json 中是否存在 storybook 脚本，或依赖项及开发依赖项中是否有 @storybook/* / storybook-*-rsbuild
3. 如果已存在 Storybook 且已使用 storybook-*-rsbuild → 已完成设置；根据需要前往配置或故障排除
4. 如果已存在 Storybook 但使用了非 Rsbuild 构建器（@storybook/*-webpack5、@storybook/*-vite 等）→ 前往迁移工作流
5. 未找到 Storybook → 前往全新设置工作流

---

全新设置工作流

1. 检测生态集成

读取 package.json 中的 dependencies 和 devDependencies，并按顺序检查：

信号	生态系统	集成指南
@rslib/core	Rslib	https://storybook.rsbuild.rs/guide/integrations/rslib
@modern-js/app-tools	Modern.js	https://storybook.rsbuild.rs/guide/integrations/modernjs
存在 @rspack/core，但没有 @rsbuild/core	Pure Rspack	https://storybook.rsbuild.rs/guide/integrations/rspack

如果匹配，请阅读集成指南，并将其中的约束作为叠加规则，与以下步骤一并遵循。

2. 检测 UI 框架

根据应用依赖（react、vue、lit 等）推断 UI 框架：

UI 框架	框架包	指南
React	storybook-react-rsbuild	https://storybook.rsbuild.rs/guide/framework/react
Vue 3	storybook-vue3-rsbuild	https://storybook.rsbuild.rs/guide/framework/vue
Vanilla JS/TS	storybook-html-rsbuild	https://storybook.rsbuild.rs/guide/framework/vanilla
Web Components	storybook-web-components-rsbuild	https://storybook.rsbuild.rs/guide/framework/web-components
React Native Web	storybook-react-native-web-rsbuild	https://storybook.rsbuild.rs/guide/framework/react-native-web

3. 配置 Storybook

1. 在单体仓库中，操作应在将承载 stories 的包内进行
2. 阅读并遵循上方匹配的框架指南；安装最新稳定版的 storybook 主版本，以及匹配的 storybook-<framework>-rsbuild 主版本（原则 2）
3. 将 @rsbuild/core 直接添加到 devDependencies，与 storybook-<framework>-rsbuild 并列（原则 3）
4. 确保 .storybook/main.* 使用正确的 framework: '<storybook-*-rsbuild>'
5. 确保 package.json 中包含 storybook dev 和 storybook build 脚本
6. 如果尚无 story 文件，至少创建一个最简示例 story（例如 src/stories/Example.stories.*），以便验证第 2 步有内容可渲染
7. 运行下方的验证

迁移工作流

阅读上游迁移指南：https://storybook.rsbuild.rs/guide/migration

按顺序执行以下步骤：

1. 检测迁移类型 — 阅读 .storybook/main.*（framework 字段和／或 core.builder）以及 package.json 依赖项，将迁移归类为“从 webpack5 迁移”或“从 Vite 迁移”，然后选择迁移指南中对应的章节
2. 确认版本兼容性 — 阅读迁移指南中的“版本兼容性”章节，根据已安装的 Storybook 版本选择正确的 storybook-rsbuild 主版本
3. 替换包 — 使用项目的包管理器（根据锁文件判断）按迁移指南中的安装／移除映射进行操作；只更改迁移所需的包。始终将 @rsbuild/core 作为直接 devDep 与新的框架包一起添加（原则 3）。暂时不要移除旧框架包或旧 devDeps——这应在验证后进行（原则 4）
4. 更新 .storybook/main.* — 按迁移指南中针对所检测框架给出的内容准确应用配置变更
5. 迁移自定义构建器钩子 — 搜索旧版构建器钩子（webpackFinal／viteFinal）；如果找到，请按照上游配置指南（https://storybook.rsbuild.rs/guide/configuration）进行转换
6. 处理附加组件兼容性 — 初始阶段保持附加组件不变。如果必须更换仅支持 webpack 的附加组件，请通过 webpackAddons 交由上游自动转换，或替换为 Rsbuild 原生版本——绝不能悄悄移除（原则 5）。请参阅迁移指南中关于附加组件的章节，了解推荐的解决方法
7. 先验证，再清理——两者都必须完成 — 运行下方的验证；通过后，在报告完成之前于同一任务中完成以下所有事项（原则 4）：
   • 从 package.json 的 devDependencies 中移除旧框架包（例如：@storybook/react-webpack5、@storybook/vue3-webpack5、@storybook/react-vite、@storybook/vue3-vite、@storybook/html-webpack5、@storybook/web-components-webpack5 等）
   • 如果旧构建器包单独列出，则将其移除（例如：@storybook/builder-webpack5、@storybook/builder-vite）
   • 从 .storybook/main.* 中删除旧版 webpackFinal／viteFinal 代码块
   • 移除不再有使用方的旧构建器专用 devDeps
   • 重新运行 pnpm install（或项目对应的包管理器命令），使锁文件反映清理结果

如果需要具体映射（版本表、包名、转换模式），而此技能中未提供，请从上游文档中获取——不要猜测。

---

验证

1. storybook dev 启动时没有错误
2. 至少有一个 story 能在浏览器中正确渲染（开发服务器干净启动并不足够——stories 中缺少 glob 匹配或框架接线错误，只会在此步骤显现）
3. HMR 正常工作
4. storybook build 成功完成
5. 检查启动日志，确认当前使用的是 Rsbuild 构建器（而不是 webpack／vite）

故障排查

• 缓存问题：删除 node_modules/.cache/storybook 并重试
• 残留配置：如果迁移后开发服务器启动失败，暂时移除自定义 rsbuildFinal 代码块以隔离问题，然后逐步重新添加
• 有关调试和其他问题，请参阅上游迁移指南中的“调试”章节以及 https://storybook.rsbuild.rs/guide/configuration

边缘情况

• Monorepo：找到存放 stories 的包；在该包中操作，而不是在根目录
• 多个 .storybook/ 目录：选择 package.json 脚本所引用的目录
• TS 路径别名：确保迁移后保留别名；有关如何配置 rsbuildFinal，请参阅上游配置指南

配置

有关 rsbuildFinal、构建器选项、TypeScript 和框架专属选项 → 阅读 https://storybook.rsbuild.rs/guide/configuration