Storybook 9.0 迁移指南

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

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

正在从 Storybook 8 之前的版本迁移？

您首先需要升级到 Storybook 8。然后再回到本指南。

主要破坏性变更

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

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

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

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

升级您的 Storybook

npx storybook@next upgrade

这将

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

Monorepo 的一些有用命令

将 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。例如，假设 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 中已弃用（但仍向后兼容）的功能，或有助于您未来提高生产力的最佳实践。

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

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