企业官网建设流程全解析

Nx 迁移 Storybook 9 完全指南：使用 @nx/storybook:migrate-9 生成器自动升级你的 Nx 工作区

【免费下载链接】nxThe Monorepo Platform that amplifies both developers and AI agents. Nx optimizes your builds, scales your CI, and fixes failed PRs automatically. Ship in half the time.项目地址: https://gitcode.com/GitHub_Trending/nx/nx

本文是 Nx 仓库中@nx/storybook:migrate-9生成器的实战指南，基于官方文档 migrate-9-generator-examples.md，并结合仓库源码深入讲解迁移流程、全部命令选项与底层实现原理。读完本文，你将掌握如何在 Nx 工作区中一键将多个项目的 Storybook 配置从 8.x 迁移到 9.x、如何自动化接受 Storybook CLI 的交互提示、如何以手动分步方式执行迁移，以及如何解读迁移摘要与排查失败项目。

背景：为什么需要 migrate-9 生成器

Storybook 9 是一个大版本（major release），在带来大量新特性与改进的同时，也引入了一些破坏性变更。对于在 Nx 工作区中使用 Storybook 的团队而言，手工逐个项目升级.storybook配置、调整依赖版本既繁琐又容易出错——尤其是当工作区中包含多个 UI 库与应用时。

为此，Nx 提供了@nx/storybook:migrate-9生成器，它在 Nx 生态中扮演"迁移编排器"的角色：Nx 负责定位工作区中所有使用 Storybook 的项目并逐一驱动 Storybook CLI 完成升级与配置自动迁移，最终汇总输出一份迁移报告。该生成器已正式注册在 generators.json 中，description 为 "Migrate to Storybook version 9."，是@nx/storybook插件对外公开的迁移工具之一（同系列还有migrate-8与migrate-10，可参见 migrate-8-generator-examples.md 与 migrate-10-generator-examples.md）。

快速开始：一行命令完成迁移

在 Nx 工作区根目录执行：

npx nx g @nx/storybook:migrate-9

运行该命令时无需传递任何选项，生成器会自动对工作区中所有已配置 Storybook 的项目启动迁移流程。运行过程中你会在终端看到 Nx 与 Storybook CLI 的混合日志，每条日志都会解释当前正在执行的步骤。

:::danger 先提交你的改动 强烈建议在运行生成器之前保证 git 历史干净（commit 当前所有改动）。因为该生成器会对工作区做出大量修改，干净的 git 历史可以让你在迁移异常时轻松回退。 :::

生成器执行流程（源码视角）

从 migrate-9.ts 的实现可以看出，生成器的核心执行顺序为：

1. 校验版本：调用assertSupportedStorybookVersion（实现见 assert-supported-storybook-version.ts），基于 versions.ts 中定义的minSupportedStorybookVersion = '8.0.0'断言当前工作区支持的 Storybook 最低版本。
2. 检查是否安装了 Storybook：通过checkStorybookInstalled检查根package.json中是否同时声明了storybook与@nx/storybook依赖。如果未安装，生成器会直接提示 "No Storybook packages installed" 并退出，不做任何改动。
3. 扫描所有 Storybook 项目：通过getAllStorybookInfo（见 helper-functions.ts）递归扫描工作区中所有.storybook/main.{ts,js,cjs,mts,mjs,cts}文件，反向推导出每个项目的configDir与项目名（依据项目根目录下的package.json/project.json中的name字段）。
4. 升级依赖：默认调用callUpgrade执行storybook@latest upgrade，将所有@storybook/*包升级到最新版本。
5. 自动迁移配置：对每个 Storybook 项目依次执行storybook automigrate --config-dir <configDir>，收集成功/失败的项目列表。
6. 输出结果：通过logResult打印迁移完成总结，并在工作区根目录生成storybook-migration-summary.md摘要文件。

生成器的完整选项

@nx/storybook:migrate-9支持四个可选项，定义于 schema.json（对应 TypeScript 类型见 schema.d.ts）：

其中noUpgrade与versionTag两个选项在原文档正文中未展开，但它们在 CI 或二次迁移场景下非常实用：例如当你已经手动执行过upgrade，再次运行生成器时可加--noUpgrade跳过重复安装；而需要试用 Storybook 9 的 beta 版本时，可指定--versionTag next。

接受 Storybook CLI 的 automigration 提示

迁移过程中，Storybook CLI（由 Nx 生成器代为驱动）会针对每个项目提示你是否运行一些代码生成器与修饰器（modifiers）。你可以对这些提示回答yes。常见提示如下（实际数量可能因你的项目配置和 Storybook CLI 版本而异——注意：这段代码并非由 Nx 维护，而是由 Storybook 维护）：

• mainjsFramework：尝试在你的项目.storybook/main.js|ts文件中添加framework字段。Storybook 9 要求显式声明 framework，这是 8→9 破坏性变更中影响面最大的一项。
• eslintPlugin：安装eslint-plugin-storybook，用于在你的 ESLint 配置中启用 Storybook 专属规则。
• newFrameworks：移除不再使用的依赖，例如@storybook/builder-webpack5、@storybook/manager-webpack5、@storybook/builder-vite——Storybook 9 将构建器整合进 framework 后，这些独立 builder 包不再需要。
• autodocsTrue：在你的项目.storybook/main.js|ts文件中添加autodocs: true，开启自动生成的文档页。

这些提示的实际执行由callAutomigrate（见 calling-storybook-cli.ts）调用 Storybook CLI 完成——Nx 负责构造storybook automigrate --config-dir <configDir>命令，并按项目逐个在子进程中执行，将输出透传给终端，然后根据退出码将项目归类到successfulProjects或failedProjects。

检查迁移结果

生成器结束后，终端会打印一份改动总结，同时会在工作区根目录生成一个名为storybook-migration-summary.md的新文件，其中列出了对工作区所做的所有改动。该文件的生成逻辑与模板定义在 storybook-migration-summary.md__tmpl__，包含以下区块：

• Upgrade Storybook packages：记录执行的升级命令（如npx storybook@latest upgrade）；
• 成功/失败的 automigration 命令清单：分别列出每个项目实际执行的automigrate命令；
• 失败排查提示：模板特别提醒检查 Storybook CLI 日志中是否出现❌ Failed trying to evaluate或❌ The migration failed to update这类消息，用于判断命令是否真正成功；
• Next steps：给出验证命令npx nx build-storybook project-name与npx nx storybook project-name。

此外，源码中handleMigrationResult还会交叉检查工作区根目录的migration-storybook.log文件：如果日志中出现了 "The migration failed to update your " 字样，即使该项目的 automigrate 命令退出码为 0，也会被判定为失败项目并移入failedProjects——这是对"命令跑完但实际未生效"情况的兜底校验。

迁移后的 .storybook/main 文件示例

迁移完成后，典型的项目级.storybook/main.js|ts文件如下。

Angular 项目完整示例

适用于使用@storybook/angular的 Angular 项目：

const config = { stories: ['../src/app/**/*.@(mdx|stories.@(js|jsx|ts|tsx)'], addons: ['@storybook/addon-essentials'], framework: { name: '@storybook/angular', options: {}, }, }; export default config;

React + Vite 项目完整示例

适用于使用 Vite 作为构建工具的 React 项目：

const config = { stories: ['../src/app/**/*.@(mdx|stories.@(js|jsx|ts|tsx)'], addons: ['@storybook/addon-essentials'], framework: { name: '@storybook/react-vite', options: { builder: { viteConfigPath: 'apps/rv1/vite.config.ts', }, }, }, }; export default config;

可以观察到，两个示例都具备共同特征：framework字段显式声明（对应mainjsFramework提示），stories与addons保持原样，而独立 builder 依赖（如@storybook/builder-vite）已被移除（对应newFrameworks提示）。React + Vite 场景下framework.options.builder.viteConfigPath会指向项目实际的 Vite 配置文件，请按你自己的项目路径核对此值是否正确。

验证迁移：运行 Storybook

迁移完成后，你可以通过常规的 Nx 命令验证一切是否正常，构建 Storybook：

npx nx build-storybook PROJECT_NAME

以及本地启动 Storybook：

npx nx storybook PROJECT_NAME

将PROJECT_NAME替换为你的实际项目名。如果构建与启动均无报错，且控制台未出现上述失败日志，即可确认迁移成功。

自动化场景：--autoAcceptAllPrompts 一键全自动迁移

如果你希望在 CI 环境或脚本中运行迁移，或者确定要接受所有提示，可以加上--autoAcceptAllPrompts标志，自动回答所有 Storybook CLI 提示：

npx nx g @nx/storybook:migrate-9 --autoAcceptAllPrompts

该标志的实际效果在 calling-storybook-cli.ts 中有两处体现：升级阶段会将命令变为storybook@latest upgrade --yes，automigrate 阶段则会在每个storybook automigrate --config-dir ...命令后追加--yes。

需要注意的是，即使加上该标志，Storybook CLI 可能仍会就个别事项向你提问，但大部分情况下整个迁移套件会在无人值守的情况下顺畅跑完。

手动分步迁移：--onlyShowListOfCommands

如果你希望以受控的方式逐步执行迁移，可以先用--onlyShowListOfCommands让生成器只打印所需命令清单，而不对代码做任何修改：

npx nx g @nx/storybook:migrate-9 --onlyShowListOfCommands

该模式对应源码中的onlyShowGuide函数：它仅向终端输出一段 "Storybook 9 Migration Guide" 文本，列出待执行命令后立即返回，绝不触碰工作区文件。本质上，手动迁移的完整流程如下：

1. 查看命令清单：运行npx nx g @nx/storybook:migrate-9 --onlyShowListOfCommands，生成器会列出针对你工作区每个 Storybook 项目定制的命令；
2. 升级 Storybook 包：执行npx storybook@latest upgrade；
3. 逐个项目运行 automigrate：针对清单中列出的每个项目，执行对应的storybook automigrate --config-dir <configDir>命令（使用 yarn 时命令中的storybook@latest会替换为storybook）。

这种手动方式特别适合需要审查每一个改动、或某个项目 automigrate 失败需要单独重试的场景。

迁移失败的处理

如果某些项目的 automigrate 失败，handleMigrationResult会在终端以红色日志打印失败项目清单，并为每个失败项目给出可手动重跑的命令；这些命令同时也会写入根目录的storybook-migration-summary.md。你可以根据摘要文件中的清单逐个项目重试，并在重试时观察 Storybook CLI 的具体报错输出。

如果你在迁移过程中发现了 Nx 侧的问题，请在 Nx 仓库提交 issue；如果是 Storybook CLI 自身的问题，则请提交到 Storybook 项目。提交时尽量附上完整的终端日志与storybook-migration-summary.md内容，方便维护者定位问题。

小结

@nx/storybook:migrate-9生成器将"升级依赖 + 逐项目自动迁移配置 + 汇总报告"三个阶段封装为一条命令，是对接 Storybook 9 大版本破坏性变更的推荐路径。无论你是直接运行npx nx g @nx/storybook:migrate-9全自动完成，还是借助--onlyShowListOfCommands分步手动执行，都可以借助根目录生成的storybook-migration-summary.md精准掌握工作区中每一项改动；遇到失败项目时，也能依据摘要中的命令与日志提示快速重试。迁移完成后，记得用npx nx build-storybook <project>与npx nx storybook <project>做一次完整验证。

【免费下载链接】nxThe Monorepo Platform that amplifies both developers and AI agents. Nx optimizes your builds, scales your CI, and fixes failed PRs automatically. Ship in half the time.项目地址: https://gitcode.com/GitHub_Trending/nx/nx