88,244
文档
Storybook Docs

Storybook 8.x 到 9.1 迁移指南

Storybook 9 改进了性能、兼容性和稳定性。其主要功能包括：

  • 🔋 Storybook Test，一个集成在 Storybook 中的“开箱即用”的测试工具
  • 🧪 组件测试
  • ♿️ 可访问性测试
  • 🛡️ 测试覆盖率
  • 🪶 包体积减小 48%
  • ⚛️ React Native 支持设备和 Web
  • 🏷️ 基于标签的故事组织

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

从 Storybook 6 或 7 迁移？

我们有以前的迁移指南：

主要破坏性更改

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

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

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

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

自动升级

要升级您的 Storybook，请在存储库的根目录中运行升级命令。

npx storybook@latest upgrade

这将：

  1. 查找存储库中的所有 Storybook 项目
  2. 对于每个项目：
    1. 确定破坏性更改中没有一项适用于您的项目
      • 如果适用，您将收到有关如何解决这些问题的说明，然后再继续。
    2. 将您的 Storybook 依赖项升级到最新版本
    3. 运行一系列自动迁移，它将：
      • 检查常见的升级任务
      • 解释必要的更改并提供指向更多信息的链接
      • 请求批准，然后自动为您执行该任务

新项目

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

npm create storybook@latest

这将：

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

故障排除

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

  1. 尝试运行doctor 命令来检查常见问题（例如重复的依赖项、不兼容的插件或版本不匹配），并查看修复建议。
  2. 如果您使用 dev 命令运行 storybook，请尝试改用 build 命令。有时 build 错误比 dev 错误更易读！
  3. 查看完整的迁移说明，其中包含 Storybook 9 中值得注意的更改的详尽列表。其中许多更改在您升级时已由自动迁移处理，但并非全部。您也可能遇到我们未知的边缘情况。
  4. 在GitHub 上搜索 Storybook 问题。如果您遇到问题，很可能其他人也遇到了。如果是这样，请为该问题投票，尝试评论中描述的任何变通方法，如果您有有用的信息可以贡献，请发表评论。
  5. 如果没有现有问题，您可以提交一个问题，最好附带一个可重现的示例。我们将密切关注 Storybook 9 的问题，因为我们正在稳定发布。

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

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

包结构更改

以下包不再发布。它们已被合并到 Storybook 的核心包 storybook 中。如果合并的包有导出，这些可以通过下表中替换的路径进行访问。有关详细信息，请参阅完整的迁移说明。

移除替换
@storybook/addon-actionsstorybook/actions
@storybook/addon-backgrounds不适用
@storybook/addon-controls不适用
@storybook/addon-highlightstorybook/highlight
@storybook/addon-interactions不适用
@storybook/addon-measure不适用
@storybook/addon-outline不适用
@storybook/addon-toolbars不适用
@storybook/addon-viewportstorybook/viewport
@storybook/manager-apistorybook/manager-api
@storybook/preview-apistorybook/preview-api
@storybook/teststorybook/test
@storybook/themingstorybook/theming

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

弃用替换
@storybook/builder-managerstorybook/internal/builder-manager
@storybook/channelsstorybook/internal/channels
@storybook/client-loggerstorybook/internal/client-logger
@storybook/componentsstorybook/internal/components
@storybook/core-commonstorybook/internal/common
@storybook/core-eventsstorybook/internal/core-events
@storybook/core-serverstorybook/internal/core-server
@storybook/csf-toolsstorybook/internal/csf-tools
@storybook/docs-toolsstorybook/internal/docs-tools
@storybook/managerstorybook/internal/manager
@storybook/node-loggerstorybook/internal/node-logger
@storybook/previewstorybook/internal/preview
@storybook/routerstorybook/internal/router
@storybook/telemetrystorybook/internal/telemetry
@storybook/typesstorybook/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
此页面有用吗？
✍️ 在 GitHub 上编辑