升级 Storybook

前端生态系统是一个快速发展的领域。无论是升级框架、库、工具，还是以上所有内容，定期的依赖升级都是生活的一部分！Storybook 提供了一些资源来帮助缓解升级的痛苦。

升级脚本

最常见的升级是 Storybook 本身。 Storybook 版本遵循语义化版本控制。我们持续发布包含错误修复的补丁版本，每隔几个月发布包含新功能的小版本，并且每年大约发布一次包含破坏性更改的大版本。

为了帮助缓解使 Storybook 保持最新的痛苦，我们提供了一个命令行脚本，该脚本可以自动检测您存储库中的所有 Storybook 项目

npx storybook@latest upgrade

重要提示：始终从存储库根目录运行升级命令。该脚本将自动检测您存储库中的所有 Storybook 项目，包括单仓设置。

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

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

upgrade 命令设计用于从一个主版本升级到下一个主版本。

✅ 好的：正在使用 Storybook 8 并运行 storybook@9 upgrade
❌ 不好：正在使用 Storybook 7 并运行 storybook@9 upgrade

如果您想跨多个主版本升级，请多次运行该命令。例如，要从 Storybook 7 升级到 Storybook 9，您需要先使用 storybook@8 upgrade 升级到 Storybook 8 的最新版本，然后运行 storybook@9 upgrade 升级到 Storybook 9 的最新版本。

这唯一的例外是当从 6 升级到 8 时，您可以直接运行 storybook@8 upgrade 从 6.x.x 升级到 8.x.x。

单仓支持

升级脚本为单仓提供了增强支持

自动检测：脚本会自动检测您存储库中的所有 Storybook 项目
选择性升级：如果您的 Storybook 项目是真正独立的（意味着每个 Storybook 项目在其自己的 package.json 中都有独立的 Storybook 依赖项），您可以选择要升级的 Storybook 项目
批量升级：如果您的 Storybook 项目共享依赖项，所有检测到的项目将一起升级以确保一致性

限制大型单仓的范围

对于大型单仓，如果您想将升级限制在特定目录，请使用 STORYBOOK_PROJECT_ROOT 环境变量

STORYBOOK_PROJECT_ROOT=./packages/frontend storybook@latest upgrade

这对于拥有半独立 Storybook 的庞大单仓尤其有用。

升级过程

运行命令后，脚本将

检测您存储库中的所有 Storybook 项目
将所有 Storybook 包升级到指定的版本
运行相关的自动迁移，考虑当前版本和指定版本之间的重大更改
自动运行 doctor 命令以验证升级

除了运行命令之外，我们还建议检查 MIGRATION.md 文件，其中包含可能影响您升级的相关更改和弃用的详细日志。

自动健康检查

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

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

npx storybook@latest doctor

错误处理和调试

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

将在存储库根目录创建一个 debug-storybook.log 文件，其中包含所有相关的日志
有关更详细的信息，请使用 --loglevel debug 标志将日志级别设置为 debug
如果需要帮助解决问题，请在 GitHub 上创建问题并附上日志

命令行选项

upgrade 命令支持多个标志来定制升级过程

storybook@latest upgrade [options]

可用标志

标志	描述
`-c, --config-dir <目录名...>`	查找 Storybook 配置的目录或目录
`--debug`	启用更多调试日志（默认值：false）
`--disable-telemetry`	禁用遥测数据发送
`--enable-crash-reports`	启用将崩溃报告发送到遥测数据
`-f, --force`	强制升级，跳过自动阻止程序
`--loglevel <级别>`	定义日志级别：`debug`、`error`、`info`、`silent`、`trace` 或 `warn`（默认值：`info`）
`--package-manager <管理器>`	强制包管理器：`npm`、`pnpm`、`yarn1`、`yarn2` 或 `bun`
`-s, --skip-check`	跳过 postinstall 版本和自动迁移检查
`--write-logs`	在运行时结束时将所有调试日志写入文件
`-y, --yes`	跳过提示用户

示例用法

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

自动迁移脚本

Storybook 升级并非唯一需要考虑的因素：生态系统的变化也带来了挑战。例如，像 Angular、Next.js 或 Svelte 这样广为人知的现代前端框架，一直在对其生态系统进行重大更改，所以即使您不升级 Storybook 版本，也可能需要相应地更新您的配置。这就是 Automigrate 的作用。

npx storybook@latest automigrate

它会运行一套标准的配置检查，解释哪些可能已过时，并提供自动修复的选项。它还会指向相关文档，以便您可以了解更多信息。它会在 storybook upgrade 命令中自动运行，但如果您不想升级 Storybook，也可以单独使用它。

预发布版本

除了以上内容，Storybook 处于持续开发中，我们几乎每天都会发布预发布版本。预发布版本是正式可用之前尝试新功能的最佳方式，我们尽最大努力保持其稳定性，尽管并非总是可能。

升级到最新的预发布版本

npx storybook@next upgrade

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

storybook@next upgrade 将升级到最新的预发布版本
storybook@8.0.0-beta.1 upgrade 将升级到 8.0.0-beta.1
storybook@8 upgrade 将升级到最新的 8.x 版本

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

Storybook 会收集完全匿名的数据来帮助我们改进用户体验。参与是可选的，如果您不想分享任何信息，可以选择退出。

故障排除

Storybook 检测不到我的 Storybook 项目

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

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

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

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

Storybook 不会自动迁移非 Storybook 文件

我们的自动迁移通常只转换和迁移 .storybook 目录中的文件以及您的 story 和 mdx 文件，这些文件被提及为 Storybook 配置的一部分。

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