立即开始
Docs
Storybook Docs

Storybook 10 迁移指南

Storybook 10 是一个重大维护版本，专注于仅 ESM 包的分发。其主要功能包括：

¥Storybook 10 is a breaking maintenance release focused on ESM-only package distribution. Its main features include:

  • 💎 仅 ESM 格式，以减小安装包大小

    ¥💎 ESM-only to reduce install size

  • ↗️ CSF Next 预览版，具有更好的类型安全性和自动补全功能。

    ¥↗️ CSF Next preview with better typesafety and autocompletion

  • 🏷 改进的基于标签的过滤

    ¥🏷 Improved tags-based filtering

即将推出：

¥Coming soon:

  • 🧪 熟悉且符合人机工程学的 CSF 测试函数（实验性）

    ¥🧪 Familiar and ergonomic CSF test functions (experimental)

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

¥This guide is meant to help you upgrade from Storybook 9.x to 10 successfully!

从 Storybook 9 之前的版本迁移？

¥Migrating from a Storybook version prior to 9?

首先，你需要安装 升级到 Storybook 9。然后，你可以返回本指南。

¥You'll first need to upgrade to Storybook 9. Then you can return to this guide.

重大重大变化

¥Major breaking changes

本指南的其余部分将帮助你成功升级，无论是自动升级还是手动升级。但是首先，Storybook 10 中包含一些 重大更改。以下是你在进一步了解之前应该了解的最具影响力的更改：

¥The rest of this guide will help you upgrade successfully, either automatically or manually. But first, there are some breaking changes in Storybook 10. Here are the most impactful changes you should know about before you go further:

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

¥If any of these changes apply to your project, please read through the linked migration notes before continuing.

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

¥If any of these new requirements or changes are blockers for your project, we recommend to continue using Storybook 8.x.

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

¥You may wish to read the full migration notes before migrating. Or you can run the upgrade command below and we’ll try to take care of everything for you!

自动升级

¥Automatic upgrade

要升级 Storybook，请在代码库的根目录中运行 upgrade 命令：

¥To upgrade your Storybook, run the upgrade command in the root of your repository:

npx storybook@latest upgrade

这将：

¥This will:

  1. 在你的代码库中查找所有 Storybook 项目

    ¥Find all of the Storybook projects in your repository

  2. 适用于每个项目

    ¥For each project

    1. 确定 重大更改 均不适用于你的项目

      ¥Determine that none of the breaking changes apply to your project

      • 如果出现问题，你将在继续之前收到有关如何解决这些问题的说明

        ¥If they do, you will receive instructions on how to resolve them before continuing

    2. 将 Storybook 依赖升级到最新版本

      ¥Upgrade your Storybook dependencies to the latest version

    3. 运行自动迁移集合，它将：

      ¥Run a collection of automigrations, which will:

      • 检查常见的升级任务

        ¥Check for common upgrade tasks

      • 解释必要的更改，并提供指向更多信息的链接

        ¥Explain the necessary changes with links to more information

      • 请求批准，然后系统将自动代表你执行任务

        ¥Ask for approval, then perform the task automatically on your behalf

新项目

¥New projects

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

¥To add Storybook to a project that isn’t currently using Storybook:

npm create storybook@latest

这将：

¥This will:

  1. 找出你正在使用的渲染器（React、Vue、Angular、Web Components）、构建器（Webpack、Vite）或元框架（Next.js、SvelteKit）

    ¥Figure out which renderer (React, Vue, Angular, Web Components), builder (Webpack, Vite), or meta-framework (Next.js, SvelteKit) you’re using

  2. 安装 Storybook 10 并自动配置以镜像项目设置

    ¥Install Storybook 10 and auto-configure it to mirror project settings

故障排除

¥Troubleshooting

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

¥The automatic upgrade should get your Storybook into a working state. If you encounter an error running Storybook after upgrading, here’s what to do:

  1. 尝试运行 doctor 命令 以检查常见问题（例如重复的依赖、不兼容的插件或不匹配的版本）并查看修复它们的建议。

    ¥Try running the doctor command to check for common issues (such as duplicate dependencies, incompatible addons, or mismatched versions) and see suggestions for fixing them.

  2. 如果你使用 dev 命令运行 storybook，请尝试使用 build 命令。有时 build 错误比 dev 错误更清晰！

    ¥If you’re running storybook with the dev command, try using the build command instead. Sometimes build errors are more legible than dev errors!

  3. 请查看 完整的迁移说明，其中包含 Storybook 10 中所有重要变更的完整列表。升级时，其中许多已经由自动迁移处理，但并非所有都是如此。你也可能遇到我们不知道的极端情况。

    ¥Check the full migration notes, which contains an exhaustive list of noteworthy changes in Storybook 10. Many of these are already handled by automigrations when you upgrade, but not all are. It’s also possible that you’re experiencing a corner case that we’re not aware of.

  4. 搜索 GitHub 上的 Storybook 问题。如果你遇到问题，其他人也很有可能遇到问题。如果是这样，请赞成该问题，尝试评论中描述的任何解决方法，如果你有有用的信息可以贡献，请回复评论。

    ¥Search Storybook issues on GitHub. If you’re seeing a problem, there’s a good chance other people are too. If so, upvote the issue, try out any workarounds described in the comments, and comment back if you have useful info to contribute.

  5. 如果没有现有问题，你可以 文件一，最好附上重现文件。在稳定版本发布期间，我们将密切关注 Storybook 10 的问题。

    ¥If there’s no existing issue, you can file one, ideally with a reproduction attached. We’ll be on top of Storybook 10 issues as we’re stabilizing the release.

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

¥If you prefer to debug yourself, here are a few useful things you can do to help narrow down the problem:

  1. 尝试删除不在 @storybook npm 命名空间中的所有插件（确保你没有删除 storybook 包）。在 9.x 版本中运行良好的社区插件可能尚未与 10.x 版本兼容，这是排除此可能性的最快方法。如果你发现某个插件需要升级才能与 Storybook 10 兼容，请在该插件的仓库中提交 issue，或者更好的是，提交 pull request 来进行升级！

    ¥Try removing all addons that are not in the @storybook npm namespace (make sure you don't remove the storybook package). Community addons that work well with 9.x might not yet be compatible with 10.x, and this is the fastest way to isolate that possibility. If you find an addon that needs to be upgraded to work with Storybook 10, please post an issue on the addon’s repository, or better yet, a pull request to upgrade it!

  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 提交问题或拉取请求，我们会尽力快速处理。

    ¥Another debugging technique is to bisect to older prerelease versions of Storybook to figure out which release broke your Storybook. For example, assuming that the current prerelease of Storybook is 10.0.0-beta.56, you could set the version to 10.0.0-alpha.0 in your package.json and reinstall to verify that it still works (alpha.0 should be nearly identical to 9.1.x). If it works, you could then try 10.0.0-beta.0, then 10.0.0-beta.28 and so forth. Once you’ve isolated the bad release, read through its CHANGELOG entry and perhaps there’s a change that jumps out as the culprit. If you find the problem, please submit an issue or pull request to the Storybook monorepo and we’ll do our best to take care of it quickly.

可选迁移

¥Optional migrations

除了上述自动迁移和手动迁移之外，还有你应该考虑的可选迁移。这些功能已在 Storybook 10 中弃用（但仍向后兼容），或可帮助你在未来提高效率的最佳实践。

¥In addition to the automigrations and manual migrations above, there are also optional migrations that you should consider. These are features that we’ve deprecated in Storybook 10 (but remain backwards compatible), or best practices that should help you be more productive in the future.

test-runner 到 addon-vitest

¥test-runner to addon-vitest

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

¥addon-vitest and the rest of the Storybook Test experience is designed to supercede the test-runner. It's faster and provides a better experience for writing and running tests. If your project uses React, Vue, or Svelte and is built with Vite, you should consider migrating to addon-vitest, by following the installation instructions.