Docs
Storybook Docs

从 Storybook 6.x 迁移到 8.0 的指南

Storybook 8 专注于提高性能、兼容性和稳定性。关键功能包括：

¥Storybook 8 focuses on improving performance, compatibility, and stability. Key features include:

本指南旨在帮助你成功从 Storybook 6.x 升级到 8.0！

¥This guide is meant to help you upgrade from Storybook 6.x to 8.0 successfully!

重大重大变化

¥Major breaking changes

本指南的其余部分将帮助你成功升级，无论是自动升级还是手动升级。但首先，我们在 Storybook 7 和 Storybook 8 中积累了很多重大变化。以下是你在进一步了解之前应该了解的最具影响力的更改：

¥The rest of this guide will help you upgrade successfully, either automatically or manually. But first, we’ve accumulated a lot of breaking changes in both Storybook 7 and Storybook 8. 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 7 的要求。

¥If any of these new requirements or changes are blockers for your project, we recommend looking at the requirements to migrate to Storybook 7.

你可能希望在迁移之前阅读 Storybook 6 至 7 和 ( 的完整迁移说明。或者你可以按照以下说明操作，我们会尽力为你处理一切！

¥You may wish to read the full migration notes for Storybook 6 to 7 and Storybook 7 to 8 before migrating. Or you can follow the instructions below and we’ll try to take care of everything for you!

自动升级

¥Automatic upgrade

要升级你的 Storybook：

¥To upgrade your Storybook:

npx storybook@latest upgrade

这将：

¥This will:

  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 on your behalf

常见升级问题

¥Common upgrade issues

虽然我们会尽力自动升级你的项目，但你在升级过程中可能会遇到两个值得一提的问题：

¥While we'll do our best to upgrade your project automatically, there are two issues worth mentioning that you might encounter during the upgrade process:

storyStoreV7:false 和 storiesOf

¥storyStoreV7:false and storiesOf

如果你的 .storybook/main.js 中有 storyStoreV7: false，则需要先将其删除，然后才能升级到 Storybook 8。

¥If you have storyStoreV7: false in your .storybook/main.js, you will need to remove it before you're able to upgrade to Storybook 8.

如果你使用的是 storiesOf API（在 Storybook 7 中需要 storyStoreV7: false），则需要使用 将你的故事迁移到 CSF 或 新的索引器 API 以继续动态创建故事。

¥If you are using the storiesOf API (which requires storyStoreV7: false in Storybook 7), you will need to either migrate your stories to CSF or use the new indexer API to continue creating stories dynamically.

MDX 1 到 MDX 3

¥MDX 1 to MDX 3

Storybook 8 使用 MDX 3。如果你来自 MDX 1（Storybook 6 使用），MDX 2 中有重大的重大变化。请参考我们的 成功升级指南。

¥Storybook 8 uses MDX 3. If you're coming from MDX 1 (used by Storybook 6), there were significant breaking changes in MDX 2. Please reference our guidance on upgrading successfully.

缺少 vite.config.js 文件

¥Missing vite.config.js file

如果你使用的是 Vite，你现在可能需要在项目根目录中创建一个 vite.config.js 文件，以允许较新版本的 Vite 与 Storybook 一起使用。此外，你可能需要为你的框架安装和配置 Vite 插件。更多信息可在 完整迁移说明 中找到。

¥If you are using Vite, you may now need to create a vite.config.js file in your project root to allow newer versions of Vite to work with Storybook. Additionally, you may need to install and configure a Vite plugin for your framework. More information is available in the full migration notes.

包结构更改

¥Package structure changes

以下软件包已被删除。有关详细信息，请参阅 完整迁移说明。

¥The following packages are removed. See the full migration notes for details.

删除替换
@storybook/addons@storybook/manager-api 或 @storyboook/preview-api
@storybook/channel-postmessage@storybook/channels
@storybook/channel-websocket@storybook/channels
@storybook/client-api@storybook/preview-api
@storybook/core-client@storybook/preview-api
@storybook/preview-web@storybook/preview-api
@storybook/store@storybook/preview-api
@storybook/api@storybook/manager-api

以下软件包已弃用。有关详细信息，请参阅 完整迁移说明。

¥The following packages are deprecated. See the full migration notes for details.

弃用替换
@storybook/testing-library@storybook/test

故障排除

¥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 8 中值得注意的更改的详尽列表。升级时，其中许多已经由自动迁移处理，但并非所有都是如此。你也可能遇到我们不知道的极端情况。

    ¥Check the full migration notes, which contains an exhaustive list of noteworthy changes in Storybook 8. 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 8 问题。

    ¥If there’s no existing issue, you can file one, ideally with a reproduction attached. We’ll be on top of Storybook 8 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 包）。与 7.x 配合良好的社区插件可能尚未与 8.0 兼容，这是隔离这种可能性的最快方法。如果你发现需要升级才能与 Storybook 8 配合使用的插件，请在插件的存储库中发布问题，或者更好的是，发布升级请求！

    ¥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 7.x might not yet be compatible with 8.0, and this is the fastest way to isolate that possibility. If you find an addon that needs to be upgraded to work with Storybook 8, please post an issue on the addon’s repository, or better yet, a pull request to upgrade it!

  2. 另一种调试技术是将 Storybook 的较旧预发布版本一分为二，以找出哪个版本破坏了你的 Storybook。例如，假设 Storybook 的当前预发布版本是 8.0.0-beta.56，你可以在 package.json 中将版本设置为 8.0.0-alpha.0，然后重新安装以验证它是否仍然有效（alpha.0 应该与 7.6.x 几乎相同）。如果有效，你可以尝试 8.0.0-beta.0，然后是 8.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 8.0.0-beta.56, you could set the version to 8.0.0-alpha.0 in your package.json and reinstall to verify that it still works (alpha.0 should be nearly identical to 7.6.x). If it works, you could then try 8.0.0-beta.0, then 8.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 7 和 8 中弃用的功能（但仍向后兼容），或者是应该有助于你在未来提高工作效率的最佳实践。

¥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 7 and 8 (but remain backwards compatible), or best practices that should help you be more productive in the future.

CSF 2 到 CSF 3

¥CSF 2 to CSF 3

有 许多好的理由 可将你的故事从 CSF 2 转换为 CSF 3。我们提供一个 codemod，在大多数情况下，它应该会自动为你进行代码更改（确保更新 glob 以适合你的文件）：

¥There are many good reasons to convert your stories from CSF 2 to CSF 3. We provide a codemod which, in most cases, should automatically make the code changes for you (make sure to update the glob to fit your files):

# Convert CSF 2 to CSF 3
npx storybook@latest migrate csf-2-to-3 --glob="**/*.stories.tsx" --parser=tsx