Storybook 8.0 迁移指南

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

• 🩻 通过 Visual Tests 插件实现的全新可视化测试工作流程
• 💨 测试构建速度提升 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 7.x 升级到 8.0！

重大breaking changes

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

• 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@latest upgrade

这将

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

常见升级问题

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

storyStoreV7:false 和 storiesOf

如果您的 .storybook/main.js 中有 storyStoreV7: false，您需要先将其移除，然后才能升级到 Storybook 8。

如果您正在使用 storiesOf API（这需要在 Storybook 7 中使用 storyStoreV7: false），您需要将您的 stories 迁移到 CSF，或者使用新的索引器 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 配合使用的插件，请在该插件的存储库上发布问题，或者更好的是，提交一个 pull request 来升级它！
2. 另一种调试技术是二分查找较旧的 Storybook 预发布版本，以找出哪个版本破坏了您的 Storybook。 例如，假设当前 Storybook 预发布版本是 8.0.0-beta.56，您可以将版本设置为 8.0.0-alpha.0 在您的 package.json 中并重新安装以验证它是否仍然有效（alpha.0 应该与 7.6.x 几乎相同）。 如果它有效，您可以尝试 8.0.0-beta.0，然后 8.0.0-beta.28，依此类推。 一旦您隔离了错误的版本，请通读其更新日志条目，也许有一个更改会突然成为罪魁祸首。 如果您找到问题，请向 Storybook monorepo 提交问题或 pull request，我们将尽力快速处理它。

包结构更改

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

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

可选迁移

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