升级 Storybook

前端生态系统是一个快速发展的地方。定期的依赖升级是一种生活方式，无论是升级框架、库、工具还是以上所有！Storybook 提供了一些资源来帮助减轻升级的痛苦。

¥The frontend ecosystem is a fast-moving place. Regular dependency upgrades are a way of life, whether upgrading a framework, library, tooling, or all of the above! Storybook provides a few resources to help ease the pain of upgrading.

升级脚本

¥Upgrade script

最常见的升级是 Storybook 本身。Storybook 发布 遵循 语义版本控制。我们不断发布带有错误修复的补丁版本，每隔几个月发布具有新功能的 Storybook 小版本，大约每年发布一次具有重大更改的 Storybook 主要版本。

¥The most common upgrade is Storybook itself. Storybook releases follow Semantic Versioning. We publish patch releases with bug fixes continuously, minor versions of Storybook with new features every few months, and major versions of Storybook with breaking changes roughly once per year.

为了帮助你减轻 Storybook 保持更新的麻烦，我们提供了一个命令行脚本，可以自动检测你存储库中的所有 Storybook 项目：

¥To help ease the pain of keeping Storybook up-to-date, we provide a command-line script that automatically detects all Storybook projects in your repository:

npx storybook@latest upgrade

upgrade 命令将使用你指定的任何版本。例如：

¥The upgrade command will use whichever version you specify. For example:

• storybook@latest upgrade 将升级到最新版本

  ¥storybook@latest upgrade will upgrade to the latest version

• storybook@8.6.1 upgrade 将升级到 8.6.1

  ¥storybook@8.6.1 upgrade will upgrade to 8.6.1

• storybook@9 upgrade 将升级到最新的 9.x.x 版本

  ¥storybook@9 upgrade will upgrade to the newest 9.x.x version

Mono-repository 支持

¥Mono-repository support

升级脚本增强了对单一存储库的支持：

¥The upgrade script provides enhanced support for mono-repositories:

• 自动检测：该脚本会自动检测仓库中的所有 Storybook 项目

  ¥Automatic detection: The script automatically detects all Storybook projects in your repository

• 选择性升级：如果你的 Storybook 真正封装（即每个 Storybook 项目在其 package.json 中都有各自独立的 Storybook 依赖），你可以选择要升级哪个 Storybook 项目。

  ¥Selective upgrades: If your Storybooks are truly encapsulated (meaning each Storybook project has its own independent Storybook dependencies in its own package.json), you can select which Storybook project to upgrade

• 批量升级：如果你的 Storybook 共享依赖，则所有检测到的项目将一起升级以确保一致性。

  ¥Bulk upgrades: If your Storybooks share dependencies, all detected projects will be upgraded together to ensure consistency

在大型单一代码库中限制范围

¥Limiting scope in large mono-repositories

对于大型单一存储库，如果你想将升级限制在特定目录，请使用 STORYBOOK_PROJECT_ROOT 环境变量：

¥For large mono-repositories where you want to limit the upgrade to a specific directory, use the STORYBOOK_PROJECT_ROOT environment variable:

STORYBOOK_PROJECT_ROOT=./packages/frontend storybook@latest upgrade

这在包含半封装 Storybook 的大型单一存储库中尤其有用。

¥This is especially helpful in huge mono-repositories with semi-encapsulated Storybooks.

升级过程

¥Upgrade process

运行命令后，脚本将：

¥After running the command, the script will:

• 检测存储库中的所有 Storybook 项目

  ¥Detect all Storybook projects in your repository

• 将所有 Storybook 软件包升级到指定版本

  ¥Upgrade all Storybook packages to the specified version

• 运行相关 automigrations，将当前版本和指定版本之间的 重大更改 考虑在内

  ¥Run the relevant automigrations factoring in the breaking changes between your current version and the specified version

• 自动运行 doctor 命令 以验证升级

  ¥Automatically run the doctor command to verify the upgrade

自动健康检查

¥Automatic health check

升级后，升级脚本会自动对所有检测到的 Storybook 项目运行健康检查。这将验证升级是否已成功完成，并检查升级后可能出现的常见问题，例如重复的依赖、不兼容的插件或不匹配的版本。

¥The upgrade script automatically runs a health check on all detected Storybook projects after the upgrade. This verifies that the upgrade was completed successfully and checks for common issues that might arise after an upgrade, such as duplicated dependencies, incompatible addons, or mismatched versions.

所有检测到的 Storybook 都会自动运行健康检查。你也可以随时使用 storybook doctor 命令手动运行它：

¥The health check runs automatically for all detected Storybooks. You can also run it manually at any time using the storybook doctor command:

npx storybook@latest doctor

错误处理和调试

¥Error handling and debugging

如果你在升级过程中遇到问题：

¥If you encounter issues during the upgrade:

1. 将在代码库根目录中创建一个包含所有相关日志的 debug-storybook.log 文件。

   ¥A debug-storybook.log file will be created in the repository root containing all relevant logs

2. 有关更多详细信息，请使用 --loglevel debug 标志将日志级别设置为 debug。

   ¥For more detailed information, set the log level to debug using the --loglevel debug flag

3. 如果你需要帮助解决问题，请使用日志创建一个 GitHub 问题。

   ¥Create a GitHub issue with the logs if you need help resolving the problem

命令行选项

¥Command-line options

升级命令支持多个标志来自定义升级过程：

¥The upgrade command supports several flags to customize the upgrade process:

storybook@latest upgrade [options]

可用标志

¥Available flags

示例用法

¥Example usage

# Upgrade with logging for debugging
storybook@latest upgrade --loglevel debug --logfile debug-storybook.log
 
# Force upgrade without prompts
storybook@latest upgrade --force --yes
 
# Upgrade specific config directories only
storybook@latest upgrade --config-dir .storybook-app .storybook-ui

自动迁移脚本

¥Automigrate script

Storybook 升级并不是唯一需要考虑的事情：生态系统的变化也带来了挑战。例如，知名的前端框架（如 Angular、Next.js 或 Svelte）已对其生态系统进行了重大更改，因此即使你不升级 Storybook 版本，也可能需要相应地更新配置。这就是 Automigrate 的用途：

¥Storybook upgrades are not the only thing to consider: changes in the ecosystem also present challenges. For example well-known frontend frameworks, such as Angular, Next.js or Svelte have been rolling out significant changes to their ecosystem, so even if you don't upgrade your Storybook version, you might need to update your configuration accordingly. That's what Automigrate is for:

npx storybook@latest automigrate

它运行一组标准配置检查，解释哪些可能过时，并自动为你修复它。它还指向相关文档，以便你了解更多信息。它作为 storybook upgrade 命令的一部分自动运行，但如果你不想升级 Storybook，它也可以单独使用。

¥It runs a set of standard configuration checks, explains what is potentially out-of-date, and offers to fix it for you automatically. It also points to the relevant documentation so you can learn more. It runs automatically as part of storybook upgrade command, but it's also available on its own if you don't want to upgrade Storybook.

预发布

¥Prereleases

除上述内容外，Storybook 还在不断发展，我们几乎每天都会发布预发布版本。预发布是在新功能普遍可用之前试用它们的最佳方式，我们尽最大努力保持它们尽可能稳定，尽管这并不总是可行的。

¥In addition to the above, Storybook is under constant development, and we publish pre-release versions almost daily. Pre-releases are the best way to try out new features before they are generally available, and we do our best to keep them as stable as possible, although this is not always possible.

要升级到最新的预发布版本：

¥To upgrade to the latest pre-release:

npx storybook@next upgrade

upgrade 命令将使用你指定的任何版本。例如：

¥The upgrade command will use whichever version you specify. For example:

• storybook@next upgrade 将升级到最新的预发布版本

  ¥storybook@next upgrade will upgrade to the newest pre-release version

• storybook@8.0.0-beta.1 upgrade 将升级到 8.0.0-beta.1

  ¥storybook@8.0.0-beta.1 upgrade will upgrade to 8.0.0-beta.1

• storybook@8 upgrade 将升级到最新的 8.x 版本

  ¥storybook@8 upgrade will upgrade to the newest 8.x version

如果你想降级到稳定版本，请手动编辑 package.json 中的软件包版本号并重新安装。

¥If you'd like to downgrade to a stable version, manually edit the package version numbers in your package.json and re-install.

故障排除

¥Troubleshooting

Storybook 无法检测到我的 Storybook 项目

¥Storybook doesn't detect my Storybook project

默认情况下，升级脚本将尝试在代码库的 .storybook 目录中查找 Storybook 配置。如果你的 Storybook 配置位于其他目录中，则可以使用 --config-dir 标志指定它。

¥By default, the upgrade script will attempt to find Storybook configuration in .storybook directories in your repository. If your Storybook configuration is located in a different directory, you can specify it using the --config-dir flag.

--config-dir 标志可以接受多个目录。

¥The --config-dir flag can accept multiple directories.

storybook@latest upgrade --config-dir .storybook-app .storybook-ui

如果你的项目可以被检测到，但在检测过程中出现错误，请检查代码库根目录中的 debug-storybook.log 文件。它将包含检测过程的完整输出，并帮助你解决问题。

¥If your project can be detected, but you get an error during the detection process, please check the debug-storybook.log file in the root of your repository. It will contain the full output of the detection process and will help you troubleshoot the issue.

Storybook 无法自动迁移非 Storybook 文件

¥Storybook doesn't automigrate non-Storybook files

我们的自动迁移通常仅转换和迁移 .storybook 目录内的文件以及故事和 mdx 文件，这些文件在 Storybook 配置中提及。

¥Our automigrations usually only transform and migrate files inside of your .storybook directory and your story and mdx files, which are mentioned as part of the Storybook configuration.

如果你有其他包含 Storybook 特定代码的文件，则可能需要手动迁移它们。

¥If you have other files that contain Storybook-specific code, you might need to manually migrate them.