Storybook 9.0 迁移指南

Storybook 9 提高了性能、兼容性和稳定性。其关键特性包括

🔋 Storybook Test，Storybook 中内置的一体化测试工具
🧪 组件测试
♿️ 可访问性测试
🛡️ 测试覆盖率
🪶 包体积减小 48%
⚛️ 用于设备和 web 的 React Native
🏷️ 基于标签的故事组织

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

要从 8 之前的 Storybook 版本迁移？

您需要先升级到 Storybook 8。然后您可以返回本指南。

主要破坏性变更

本指南的其余部分将帮助您成功升级，无论是自动还是手动。但首先，Storybook 9 中有一些破坏性变更。在您继续之前，这里有一些您应该了解的最具影响力的变更

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

如果这些新要求或变更对您的项目造成阻碍，我们建议您继续使用 Storybook 8.x。

您可能希望在迁移之前阅读完整的迁移说明。或者您可以运行下面的升级命令，我们将尽力为您处理所有事情！

自动升级

升级您的 Storybook

npx storybook@next upgrade

这将

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

正在迁移 monorepo 项目？请确保在包含 storybook 包的当前工作目录 (cwd) 中运行该命令。

一些对 monorepos 有用的命令

对于 NX 项目，您可以使用 nx migrate 命令
--config-dir CLI 标志可用于指定与默认 ./.storybook 目录不同的配置目录

新项目

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

npm create storybook@latest

这将

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

故障排除

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

尝试运行doctor 命令来检查常见问题（例如重复的依赖项、不兼容的插件或版本不匹配）并查看修复建议。
如果您使用 dev 命令运行 storybook，请尝试改用 build 命令。有时 build 错误比 dev 错误更容易理解！
检查完整的迁移说明，其中包含 Storybook 9 中值得注意的变更的完整列表。许多这些变更在您升级时已通过自动迁移处理，但并非所有都已处理。您也可能遇到了我们不知道的边缘情况。
在GitHub 上搜索 Storybook 问题。如果您遇到了问题，很有可能其他人也遇到了。如果是这样，请给该问题点赞，尝试评论中描述的任何临时解决方案，如果您有有用的信息要贡献，请回帖。
如果不存在现有问题，您可以创建一个，最好附带一个重现步骤。在 Storybook 9 版本稳定期间，我们将密切关注相关问题。

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

尝试移除所有不在 @storybook npm 命名空间中的插件（确保您没有移除 storybook 包）。与 8.x 配合良好的社区插件可能尚未与 9.0 兼容，这是隔离这种可能性最快的方法。如果您发现需要升级才能与 Storybook 9 配合使用的插件，请在该插件的仓库中发布问题，或者更好的是，提交一个升级它的拉取请求！
另一种调试技巧是二分法寻找旧的预发布版本，以确定是哪个版本导致您的 Storybook 出现问题。例如，假设 Storybook 当前的预发布版本是 9.0.0-beta.56，您可以在 package.json 中将版本设置为 9.0.0-alpha.0 并重新安装以验证它是否仍然工作（alpha.0 应该与 8.6.x 几乎相同）。如果它工作，您可以尝试 9.0.0-beta.0，然后是 9.0.0-beta.28 等等。一旦您找到了有问题的版本，阅读其CHANGELOG 条目，也许会有一个变更让您觉得它是罪魁祸首。如果您找到了问题，请向 Storybook monorepo 提交问题或拉取请求，我们将尽力快速解决。

包结构变更

以下软件包不再发布。相反，它们已合并到 Storybook 的核心包 storybook 中。如果合并后的包有导出，则可以通过下表中的替换路径使用。有关详细信息，请参阅完整的迁移说明。

移除	替换
`@storybook/addon-actions`	`storybook/actions`
`@storybook/addon-backgrounds`	不适用
`@storybook/addon-controls`	不适用
`@storybook/addon-highlight`	`storybook/highlight`
`@storybook/addon-interactions`	不适用
`@storybook/addon-measure`	不适用
`@storybook/addon-outline`	不适用
`@storybook/addon-toolbars`	不适用
`@storybook/addon-viewport`	`storybook/viewport`
`@storybook/manager-api`	`storybook/manager-api`
`@storybook/preview-api`	`storybook/preview-api`
`@storybook/test`	`storybook/test`
`@storybook/theming`	`storybook/theming`

以下软件包已合并并移至内部路径，以表明它们现在仅供内部使用。它们将在 9.x 版本中继续工作，但很可能在 10.0 中移除。有关详细信息，请参阅完整的迁移说明。

已弃用	替换
`@storybook/builder-manager`	`storybook/internal/builder-manager`
`@storybook/channels`	`storybook/internal/channels`
`@storybook/client-logger`	`storybook/internal/client-logger`
`@storybook/components`	`storybook/internal/components`
`@storybook/core-common`	`storybook/internal/common`
`@storybook/core-events`	`storybook/internal/core-events`
`@storybook/core-server`	`storybook/internal/core-server`
`@storybook/csf-tools`	`storybook/internal/csf-tools`
`@storybook/docs-tools`	`storybook/internal/docs-tools`
`@storybook/manager`	`storybook/internal/manager`
`@storybook/node-logger`	`storybook/internal/node-logger`
`@storybook/preview`	`storybook/internal/preview`
`@storybook/router`	`storybook/internal/router`
`@storybook/telemetry`	`storybook/internal/telemetry`
`@storybook/types`	`storybook/internal/types`

插件作者可以继续使用内部软件包，目前还没有任何替代方案。

可选迁移

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

`test-runner` 到 `addon-vitest`

addon-vitest 以及其余的Storybook Test 体验旨在取代 test-runner。它更快，并提供更好的编写和运行测试的体验。如果您的项目使用 React、Vue 或 Svelte 并使用 Vite 构建，您应该考虑迁移到 addon-vitest，按照安装说明进行操作。

CSF 2 到 CSF 3

将故事从 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