Storybook 8.0 迁移指南

Storybook 8 专注于提升性能、兼容性和稳定性。主要功能包括

• 🩻 通过 视觉测试插件 提供新的视觉测试工作流
• 💨 测试构建速度提升 2-4 倍，React docgen 速度提升 25-50%，以及 Webpack 项目支持 SWC
• 🧩 提升框架支持：使用非 React 渲染器时，不再需要安装 React 作为对等依赖项
• 🎛️ 增强了 React 和 Vue 项目中的控件生成
• ⚡️ 提升了 Vite 架构、Vitest 测试和 Vite 5 支持
• 🌐 支持 React 服务器组件 (RSC)：我们的实验性解决方案在浏览器中渲染异步 RSC 并模拟 Node 代码
• ✨ 更新了桌面 UI 和移动端 UX
• ➕ 还有更多功能

本指南旨在帮助您**成功地从 Storybook 7.x 升级到 8.0**！

重大更改

本指南的其余部分将帮助您成功升级，无论是自动还是手动。但在继续之前，Storybook 8 中有一些重大更改。以下是您在继续之前应该了解的一些最重大的更改

• storiesOf API 已移除
• *.stories.mdx 格式已移除
• 包已合并/移除
• 隐式操作（来自argTypesRegex）在渲染过程中（例如在播放函数中）不再可用
• react-docgen（而不是react-docgen-typescript）是组件分析的默认值
• Storyshots 已移除
• Storybook 7 中引入的插件 API 现在是必需的
• 生态系统更新
  • 现在需要 Node 18+
  • 现在需要 Next.js 13.5+
  • 现在需要 Vue 3+
  • 现在需要 Angular 15+
  • 现在需要 Svelte 4+
  • Yarn 1 不再受支持

如果这些更改中的任何一项适用于您的项目，请在继续之前阅读链接的迁移说明。

如果这些新要求或更改中的任何一项对您的项目造成了阻碍，我们建议您继续使用 Storybook 7.x。

在迁移之前，您可能希望阅读完整的迁移说明。或者，您可以按照以下说明操作，我们将尽力为您处理所有事情！

自动升级

要升级您的 Storybook

npx storybook@latest upgrade

这将

1. 确定您的项目中没有应用任何重大更改
   • 如果确实存在，您将在继续之前收到有关如何解决它们的说明
2. 将您的 Storybook 依赖项升级到最新版本
3. 运行一系列的自动迁移，这些迁移将
   • 检查常见升级任务
   • 解释必要的更改，并提供更多信息的链接
   • 请求批准，然后代表您执行任务

常见升级问题

虽然我们会尽最大努力自动升级您的项目，但在升级过程中您可能会遇到一个值得一提的问题

storyStoreV7:false 和 storiesOf

如果您在 .storybook/main.js 文件中设置了 storyStoreV7: false，则需要在升级到 Storybook 8 之前将其移除。

如果您正在使用 storiesOf API（在 Storybook 7 中需要 storyStoreV7: false），则需要 将您的故事迁移到 CSF 或使用 新的索引器 API 继续动态创建故事。

缺少 vite.config.js 文件

如果您正在使用 Vite，您可能需要在项目根目录中创建一个 vite.config.js 文件，以允许更新版本的 Vite 与 Storybook 协同工作。此外，您可能需要安装和配置框架的 Vite 插件。更多信息请参见 完整迁移说明。

新项目

将 Storybook 添加到当前未使用 Storybook 的项目中

npx storybook@latest init

这将

1. 确定您正在使用哪个渲染器（React、Vue、Angular、Web Components）、构建器（Webpack、Vite）或元框架（Next.js、SvelteKit）
2. 安装 Storybook 8 并自动配置以镜像项目设置

手动迁移

除了上述自动升级之外，可能还需要进行一些手动迁移才能使 Storybook 8 在您的项目中正常工作。我们已尽量减少此列表，以便于升级。这些包括：

*.stories.mdx 到 MDX+CSF

Storybook 现在要求 MDX 页面引用以 CSF 编写的 Story，而不是之前的 .stories.mdx 混合方法。您可以使用以下代码修改自动转换文件（确保更新 glob 以匹配您的文件）

# Convert stories in MDX to CSF
npx storybook@latest migrate mdx-to-csf --glob "src/**/*.stories.mdx"

如果您还没有这样做，则还需要更新 .storybook/main.js 中的 Story glob 以包含新创建的 .mdx 和 .stories.js 文件。

已知限制

• 代码修改不会从 .stories.mdx 文件中移除提取的故事。您需要手动执行此操作。

注意：此迁移支持 Storybook 6 的 "带有 MDX 文档的 CSF Story" 方案。

故障排除

自动升级应该可以让您的 Storybook 进入工作状态。如果您在升级后遇到运行 Storybook 的错误，请执行以下操作：

1. 尝试运行 doctor 命令 以检查常见问题（例如重复的依赖项、不兼容的插件或版本不匹配），并查看修复建议。
2. 如果您使用 dev 命令运行 storybook，请尝试使用 build 命令代替。有时 build 错误比 dev 错误更易读！
3. 查看 完整迁移说明，其中包含 Storybook 8 中值得注意的更改的详尽列表。其中许多更改在您升级时已由自动迁移处理，但并非全部。您也可能遇到我们不知道的特殊情况。
4. 搜索 GitHub 上的 Storybook 问题。如果您遇到问题，其他人很可能也遇到过。如果是这样，请为该问题投票，尝试评论中描述的任何解决方法，并在您有有用的信息可以贡献时进行回复。
5. 如果没有现有的问题，您可以 提交一个，理想情况下，请附上重现步骤。在我们稳定发布版本时，我们会关注 Storybook 8 的问题。

如果您更喜欢自己调试，以下是一些有助于缩小问题范围的有用方法：

1. 尝试删除所有不在 @storybook npm 命名空间中的插件（确保您没有删除 storybook 包）。与 7.x 兼容的社区插件可能尚未与 8.0 兼容，这是隔离此可能性的最快方法。如果您发现需要升级才能与 Storybook 8 协同工作的插件，请在插件的存储库中发布一个问题，或者更好的是，提交一个升级请求！
2. 另一种调试技术是将 Storybook 分割成较旧的预发布版本，以确定哪个版本破坏了您的 Storybook。例如，假设 Storybook 的当前预发布版本是 8.0.0-beta.56，您可以在 package.json 中将版本设置为 8.0.0-alpha.0 并重新安装以验证它是否仍然有效（alpha.0 应该与 7.6.x 几乎相同）。如果它有效，您可以尝试 8.0.0-beta.0，然后 8.0.0-beta.28，依此类推。一旦您隔离了有问题的版本，请阅读其 更改日志 条目，也许会有一个更改作为罪魁祸首。如果您发现了问题，请向 Storybook 单一存储库提交一个问题或请求请求，我们会尽最大努力快速解决它。

包结构更改

以下软件包已移除。有关详细信息，请参阅 完整迁移说明。

以下软件包已弃用。有关详细信息，请参阅 完整迁移说明。

可选迁移

除了以上自动迁移和手动迁移之外，您还应该考虑一些可选迁移。这些是我们已在 Storybook 8 中弃用（但仍向后兼容）的功能，或者有助于您将来提高生产力的最佳实践。

CSF 2 到 CSF 3

将您的故事从 CSF 2 转换为 CSF 3 有许多充分的理由。我们提供了一个代码修改工具，在大多数情况下，它应该可以自动为您进行代码更改（请确保更新 glob 以匹配您的文件）。

# Convert CSF 2 to CSF 3
npx storybook@latest migrate csf-2-to-3 --glob="**/*.stories.tsx" --parser=tsx