从 Storybook 7.x 迁移到 8.0 的指南

Storybook 8 着重于提升性能、兼容性和稳定性。主要特性包括

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

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

主要破坏性变更

本指南的其余部分将帮助您成功进行自动或手动升级。但首先，Storybook 8 中有一些破坏性变更。以下是您在继续之前应该了解的最重要的变更

• storiesOf API 已被移除
• *.stories.mdx 格式已被移除
• 包已被整合/移除
• 隐式 actions（来自 argTypesRegex）在渲染时（例如在 play 函数中）不再可用
• react-docgen（而非 react-docgen-typescript）成为组件分析的默认工具
• Storyshots 已被移除
• Storybook 7 中引入的 Addons API 现已强制要求使用
• 生态系统更新
  • 现在需要 Node 18+
  • 现在需要 Next.js 13.5+
  • 现在需要 Vue 3+
  • 现在需要 Angular 15+
  • 现在需要 Svelte 4+
  • 不再支持 Yarn 1

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

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

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

自动升级

升级您的 Storybook

npx storybook@next upgrade

这将

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

常见升级问题

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

storyStoreV7:false 和 storiesOf

如果您的 .storybook/main.js 中有 storyStoreV7: false，您需要在升级到 Storybook 8 之前将其移除。

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

缺少 vite.config.js 文件

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

新项目

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

npm create storybook@latest

这将

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

手动迁移

除了上面的自动升级之外，您可能还需要进行手动迁移，以使 Storybook 8 在您的项目中正常工作。我们已尽量缩短此列表，以便于升级。其中包括

*.stories.mdx 迁移到 MDX+CSF

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

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

如果您的 .storybook/main.js 中的 stories glob 尚未包含新创建的 .mdx 和 .stories.js 文件，您还需要更新它。

已知限制

• codemod 不会从 .stories.mdx 文件中移除提取的 stories。您需要手动执行此操作。

注意：此迁移支持 Storybook 6 的“带 MDX 文档的 CSF stories”方案。

故障排除

自动升级应该能让您的 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 一同工作，请在该插件的仓库中提交一个 issue，或者更好的方式是提交一个拉取请求来升级它！
2. 另一种调试技术是使用二分法回溯到较旧的预发布版本，以找出哪个版本破坏了您的 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 monorepo 提交一个 issue 或拉取请求，我们将尽最大努力尽快解决它。

包结构变更

以下包已被移除。详情请参阅完整的迁移说明。

以下包已被弃用。详情请参阅完整的迁移说明。

可选迁移

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

CSF 2 迁移到 CSF 3

将您的 stories 从 CSF 2 转换为 CSF 3 有很多好处。我们提供了一个 codemod，在大多数情况下，它应该会自动为您完成代码更改（确保更新 glob 以匹配您的文件）

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