Storybook 6.x 到 8.0 的迁移指南
Storybook 8 专注于提升性能、兼容性和稳定性。主要功能包括
- 🩻 通过 Visual Tests 插件实现的全新可视化测试工作流程
- 💨 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 6.x 升级到 8.0！
重大breaking changes
本指南的其余部分将帮助您成功升级，无论是自动还是手动。但首先，我们在 Storybook 7 和 Storybook 8 中积累了很多breaking changes。以下是在您继续之前应该了解的最具影响力的更改
framework字段现在是强制性的- 启动和构建 CLI 二进制文件已移除
storiesOfAPI 已被移除*.stories.mdx格式已被移除- 软件包已被合并/移除
- 隐式 actions（来自
argTypesRegex）在渲染期间（例如在 play 函数中）不再可用 react-docgen（而不是react-docgen-typescript）是组件分析的默认选项- Storyshots 已被移除
- Storybook 7 中引入的 Addons API 现在是必需的
- 生态系统更新
如果这些更改中的任何一项适用于您的项目，请在继续之前通读链接的迁移说明。
如果这些新要求或更改中的任何一项对您的项目造成阻碍，我们建议查看迁移到 Storybook 7 的要求。
您可能希望在迁移之前阅读 Storybook 6 到 7 和 Storybook 7 到 8 的完整迁移说明。或者您可以按照以下说明操作，我们将尽力为您处理一切！
自动升级
要升级您的 Storybook
npx storybook@latest upgrade这将
- 确定breaking changes中没有一项适用于您的项目
- 如果适用，您将收到有关如何在继续之前解决这些问题的说明
- 将您的 Storybook 依赖项升级到最新版本
- 运行一系列自动迁移，这将
- 检查常见的升级任务
- 解释必要的更改，并提供指向更多信息的链接
- 请求批准，然后代表您执行任务
常见升级问题
虽然我们将尽力自动升级您的项目，但有两件事值得一提，您可能会在升级过程中遇到
storyStoreV7:false 和 storiesOf
如果您的 .storybook/main.js 中有 storyStoreV7: false，您需要先将其删除，然后才能升级到 Storybook 8。
如果您正在使用 storiesOf API（在 Storybook 7 中需要 storyStoreV7: false），您需要将您的 stories 迁移到 CSF，或者使用新的 indexer API 来继续动态创建 stories。
MDX 1 到 MDX 3
Storybook 8 使用 MDX 3。如果您是从 MDX 1（Storybook 6 使用）升级而来，MDX 2 中有重大的breaking changes。请参考我们关于成功升级的指南。
缺少 vite.config.js 文件
如果您正在使用 Vite，您现在可能需要在项目根目录中创建一个 vite.config.js 文件，以允许较新版本的 Vite 与 Storybook 一起工作。此外，您可能需要为您的框架安装和配置一个 Vite 插件。更多信息请参见完整的迁移说明。
包结构变更
以下软件包已被移除。详情请参见完整的迁移说明。
| 移除 | 替换 |
|---|---|
@storybook/addons | @storybook/manager-api 或 @storyboook/preview-api |
@storybook/channel-postmessage | @storybook/channels |
@storybook/channel-websocket | @storybook/channels |
@storybook/client-api | @storybook/preview-api |
@storybook/core-client | @storybook/preview-api |
@storybook/preview-web | @storybook/preview-api |
@storybook/store | @storybook/preview-api |
@storybook/api | @storybook/manager-api |
以下软件包已被弃用。详情请参见完整的迁移说明。
| 弃用 | 替换 |
|---|---|
@storybook/testing-library | @storybook/test |
故障排除
自动升级应该使您的 Storybook 进入工作状态。如果在升级后运行 Storybook 时遇到错误，请执行以下操作
- 尝试运行
doctor命令以检查常见问题（例如重复的依赖项、不兼容的插件或版本不匹配），并查看有关修复它们的建议。 - 如果您正在使用
dev命令运行storybook，请尝试改用build命令。有时build命令的错误信息比dev命令的错误信息更易于理解！ - 查看完整迁移说明，其中包含了 Storybook 8 中值得注意的更改的完整列表。其中许多更改在您升级时已通过自动迁移处理，但并非全部。您也可能遇到了我们尚未意识到的边缘情况。
- 在 GitHub 上搜索 Storybook issues。如果您遇到了问题，很可能其他人也遇到了。如果是这样，请为该 issue 投票，尝试评论中描述的任何解决方法，并在您有有用的信息可以贡献时回复评论。
- 如果不存在现有 issue，您可以提交一个 issue，最好附上复现步骤。在我们稳定发布版本期间，我们会密切关注 Storybook 8 的 issue。
如果您更喜欢自行调试，以下是一些有用的方法，可以帮助您缩小问题范围
- 尝试移除所有不在
@storybooknpm 命名空间中的 addon（请确保不要移除storybook包）。与 7.x 版本配合良好的社区 addon 可能尚不兼容 8.0 版本，这是隔离这种可能性的最快方法。如果您发现某个 addon 需要升级才能与 Storybook 8 配合使用，请在该 addon 的仓库中发布一个 issue，或者更好的是，提交一个 pull request 来升级它！ - 另一种调试技术是回溯到 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 monorepo 提交 issue 或 pull request，我们将尽力尽快处理。
可选迁移
除了上述的自动迁移和手动迁移之外，还有一些您应该考虑的可选迁移。这些是在 Storybook 7 和 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