Docs 迁移到 8.0
Storybook Docs

Storybook 8.0 迁移指南

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

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

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

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

从 Storybook 6.x 迁移？

¥Migrating from Storybook 6.x?

我们有专用的 Storybook 6 到 8 的迁移指南。

¥We have a dedicated migration guide for Storybook 6 to 8.

重大重大变化

¥Major breaking changes

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

¥The rest of this guide will help you upgrade successfully, either automatically or manually. But first, there are some breaking changes in 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.x。

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

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

¥You may wish to read the full migration notes 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 is one issue 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.

缺少 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.

新项目

¥New projects

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

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

npx storybook@latest init

这将：

¥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 8 并自动配置它以镜像项目设置

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

手动迁移

¥Manual migrations

除了上述自动升级之外，可能还需要手动迁移才能让 Storybook 8 在你的项目中运行。我们已尝试最小化此列表以使其更易于升级。这些包括：

¥In addition to the automated upgrades above, there are manual migrations that might be required to get Storybook 8 working in your project. We’ve tried to minimize this list to make it easier to upgrade. These include:

*.stories.mdx 至 MDX+CSF

¥*.stories.mdx to MDX+CSF

Storybook 现在要求 MDX 页面引用用 CSF 编写的故事，而不是以前的 .stories.mdx 混合方法。你可以使用以下 codemod 自动转换文件（确保更新 glob 以适合你的文件）：

¥Storybook now requires that MDX pages reference stories written in CSF, rather than the previous .stories.mdx hybrid approach. You can automatically convert your files using the following codemod (make sure to update the glob to fit your files):

# Convert stories in MDX to CSF
npx storybook@latest migrate mdx-to-csf --glob "src/**/*.stories.mdx"

你还需要更新 .storybook/main.js 中的故事 glob 以包含新创建的 .mdx 和 .stories.js 文件（如果尚未更新）。

¥You’ll also need to update your stories glob in .storybook/main.js to include the newly created .mdx and .stories.js files if it doesn’t already.

已知限制

¥Known limitations

  • codemod 不会从 .stories.mdx 文件中删除提取的故事。你需要手动执行此操作。

    ¥The codemod does not remove the extracted stories from the .stories.mdx files. You will need to do this manually.

注意：此迁移支持 Storybook 6 "带有 MDX 文档的 CSF 故事" 秘诀。

¥Note: this migration supports the Storybook 6 "CSF stories with MDX docs" recipe.

故障排除

¥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.

包结构更改

¥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

可选迁移

¥Optional migrations

除了上述自动迁移和手动迁移之外，还有你应该考虑的可选迁移。这些是我们在 Storybook 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 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