从 Storybook 8.x 迁移到 9.1 的迁移指南

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

¥Storybook 9 improves performance, compatibility, and stability. Its key features include:

🔋 Storybook Test，Storybook 中功能强大的测试工具

¥🔋 Storybook Test, a batteries-included testing tool in your Storybook
🧪 组件测试

¥🧪 Component testing
♿️ 无障碍测试

¥♿️ Accessibility testing
🛡️ 测试覆盖率

¥🛡️ Test coverage
🪶 48% 轻量级软件包

¥🪶 48% lighter bundle
⚛️ 适用于设备和 Web 的 React Native

¥⚛️ React Native for device and web
🏷️ 基于标签的故事组织

¥🏷️ Tags-based story organization

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

¥This guide is meant to help you upgrade from Storybook 8.x to 9.1 successfully!

从 Storybook 6 或 7 迁移？

¥Migrating from Storybook 6 or 7?

我们之前提供过以下迁移指南：

¥We have prior migration guides for:

重大重大变化

¥Major breaking changes

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

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

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

¥Find all of the Storybook projects in your repository
适用于每个项目

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

找出你正在使用的渲染器（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
安装 Storybook 9 并将其自动配置为镜像项目设置。

¥Install Storybook 9 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:

尝试运行 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.
如果你使用 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!
检查完整的迁移说明，其中包含 Storybook 9 中值得注意的变更的详尽列表。升级时，其中许多已经由自动迁移处理，但并非所有都是如此。你也可能遇到我们不知道的极端情况。

¥Check the full migration notes, which contains an exhaustive list of noteworthy changes in Storybook 9. 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.
搜索 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.
如果没有现有问题，你可以文件一，最好附上重现文件。在稳定版本的过程中，我们将密切关注 Storybook 9 的问题。

¥If there’s no existing issue, you can file one, ideally with a reproduction attached. We’ll be on top of Storybook 9 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:

尝试删除不在 @storybook npm 命名空间中的所有插件（确保你没有删除 storybook 包）。在 8.x 中运行良好的社区插件可能尚未兼容 9.x，这是排除这种可能性的最快方法。如果你发现需要升级才能与 Storybook 9 兼容的插件，请在插件的存储库中发布问题，或者更好的是，提交升级请求！

¥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 8.x might not yet be compatible with 9.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 9, please post an issue on the addon’s repository, or better yet, a pull request to upgrade it!
另一种调试技术是将 Storybook 的较旧预发布版本一分为二，以找出哪个版本破坏了你的 Storybook。例如，假设 Storybook 的当前预发布版本是 9.0.0-beta.56，你可以在 package.json 中将版本设置为 9.0.0-alpha.0，然后重新安装以验证它是否仍然有效（alpha.0 应该与 8.6.x 几乎相同）。如果有效，你可以尝试 9.0.0-beta.0，然后是 9.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 9.0.0-beta.56, you could set the version to 9.0.0-alpha.0 in your package.json and reinstall to verify that it still works (alpha.0 should be nearly identical to 8.6.x). If it works, you could then try 9.0.0-beta.0, then 9.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

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

¥The following packages are no longer published. Instead they have been consolidated into Storybook's core package, storybook. If a consolidated package had exports, those are available via the replacement path in the table below. See the full migration notes for details.

删除	替换
`@storybook/addon-actions`	`storybook/actions`
`@storybook/addon-backgrounds`	N/A
`@storybook/addon-controls`	N/A
`@storybook/addon-highlight`	`storybook/highlight`
`@storybook/addon-interactions`	N/A
`@storybook/addon-measure`	N/A
`@storybook/addon-outline`	N/A
`@storybook/addon-toolbars`	N/A
`@storybook/addon-viewport`	`storybook/viewport`
`@storybook/manager-api`	`storybook/manager-api`
`@storybook/preview-api`	`storybook/preview-api`
`@storybook/test`	`storybook/test`
`@storybook/theming`	`storybook/theming`

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

¥The following packages have been consolidated and moved into an internal path to indicate that they are now for internal usage only. They will continue to work in 9.x releases, but will likely be removed in 10.0. See the full migration notes for details.

弃用	替换
`@storybook/builder-manager`	`storybook/internal/builder-manager`
`@storybook/channels`	`storybook/internal/channels`
`@storybook/client-logger`	`storybook/internal/client-logger`
`@storybook/components`	`storybook/internal/components`
`@storybook/core-common`	`storybook/internal/common`
`@storybook/core-events`	`storybook/internal/core-events`
`@storybook/core-server`	`storybook/internal/core-server`
`@storybook/csf-tools`	`storybook/internal/csf-tools`
`@storybook/docs-tools`	`storybook/internal/docs-tools`
`@storybook/manager`	`storybook/internal/manager`
`@storybook/node-logger`	`storybook/internal/node-logger`
`@storybook/preview`	`storybook/internal/preview`
`@storybook/router`	`storybook/internal/router`
`@storybook/telemetry`	`storybook/internal/telemetry`
`@storybook/types`	`storybook/internal/types`

插件作者可以继续使用内部软件包，目前尚无任何替代品。

¥Addon authors may continue to use the internal packages, there is currently not yet any replacement.

可选迁移

¥Optional migrations

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

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

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