Storybook 10 迁移指南

Storybook 10 包含一项重大变更：它仅支持 ESM。这简化了我们的分发，并将安装大小减少了 29%，同时使 dist 代码可以被取消最小化，以便于调试。

它还包含了一些功能，可以提升您的 UI 开发、文档和测试工作流程。

• 🧩 模块自动模拟，便于测试
• 🏭 React 的类型安全 CSF 工厂预览
• 💫 UI 编辑和共享优化
• 🏷️ 标签过滤排除和侧边栏管理配置
• 🔀 Svelte 异步组件支持等更多功能

本指南旨在帮助您成功地**从 Storybook 9.x 升级到 10**！

重大的破坏性变更

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

• 主配置（.storybook/main.js|ts）和其他预设必须是有效的 ESM。
• 生态系统更新
  • 现在需要 Node 20.19+ 或 22.12+。

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

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

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

自动升级

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

npx storybook@latest upgrade

这会：

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

新项目

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

npm create storybook@latest

这会：

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

故障排除

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

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

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

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

可选迁移

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

test-runner 到 addon-vitest

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