Storybook 6.x 到 8.0 的迁移指南

Storybook 8 侧重于提高性能、兼容性和稳定性。 主要功能包括

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

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

重大变更

本指南的其余部分将帮助您成功升级，无论是自动还是手动升级。 但首先，我们在 Storybook 7 和 Storybook 8 中积累了许多重大变更。 在继续之前，您应该了解以下最具影响力的变更

• framework 字段现在是必需的
• 启动和构建 CLI 二进制文件已删除
• storiesOf API 已删除
• *.stories.mdx 格式已删除
• 软件包已合并/删除
• 在渲染期间（例如，在播放函数中）不再可以使用隐式操作（来自 argTypesRegex）
• react-docgen（而不是 react-docgen-typescript）是组件分析的默认值
• Storyshots 已删除
• Storybook 7 中引入的附加组件 API 现在是必需的
• 生态系统更新
  • Webpack4 支持已停止
  • IE11 支持已停止
  • 现在需要 Node 18+
  • 现在需要 Next.js 13.5+
  • 现在需要 Vue 3+
  • 现在需要 Angular 15+
  • 现在需要 Svelte 4+
  • Yarn 1 不再受支持

如果您的项目中存在任何这些变更，请在继续之前阅读相关联的迁移说明。

如果任何这些新的要求或变更对您的项目造成了阻碍，我们建议您查看 迁移到 Storybook 7 的要求。

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

自动升级

要升级您的 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 来继续动态创建故事。

MDX 1 到 MDX 3

Storybook 8 使用 MDX 3。如果您来自使用 Storybook 6 的 MDX 1，MDX 2 中存在重大破坏性更改。请参考我们的 成功升级指南。

缺少 vite.config.js 文件

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

包结构更改

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

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

故障排除

自动升级应该会使您的 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 等等。一旦您找到了出现问题的版本，请阅读其 CHANGELOG 条目，也许其中有跳出来的更改可能是罪魁祸首。如果您找到了问题，请向 Storybook 单体存储库提交一个问题或拉取请求，我们将尽力快速处理它。

可选迁移

除了上述的自动迁移和手动迁移外，您还应该考虑可选迁移。这些是我们已在 Storybook 7 和 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