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 的实现可以看出生成器的核心执行顺序为校验版本调用assertSupportedStorybookVersion实现见 assert-supported-storybook-version.ts基于 versions.ts 中定义的minSupportedStorybookVersion 8.0.0断言当前工作区支持的 Storybook 最低版本。检查是否安装了 Storybook通过checkStorybookInstalled检查根package.json中是否同时声明了storybook与nx/storybook依赖。如果未安装生成器会直接提示 No Storybook packages installed 并退出不做任何改动。扫描所有 Storybook 项目通过getAllStorybookInfo见 helper-functions.ts递归扫描工作区中所有.storybook/main.{ts,js,cjs,mts,mjs,cts}文件反向推导出每个项目的configDir与项目名依据项目根目录下的package.json/project.json中的name字段。升级依赖默认调用callUpgrade执行storybooklatest upgrade将所有storybook/*包升级到最新版本。自动迁移配置对每个 Storybook 项目依次执行storybook automigrate --config-dir configDir收集成功/失败的项目列表。输出结果通过logResult打印迁移完成总结并在工作区根目录生成storybook-migration-summary.md摘要文件。生成器的完整选项nx/storybook:migrate-9支持四个可选项定义于 schema.json对应 TypeScript 类型见 schema.d.ts选项类型默认值说明autoAcceptAllPromptsbooleanfalse自动回答是给 Storybook CLI 迁移脚本提出的所有交互式提示onlyShowListOfCommandsbooleanfalse只打印需要手动执行的迁移步骤清单不会对代码做任何修改noUpgradebooleanfalse跳过 Storybook 包升级步骤。仅当你已经处于 9.x 且不希望重新安装依赖时使用versionTagstringlatest要使用的 Storybook 版本标签latest表示最新稳定版next表示最新测试版枚举值限定为latest/next其中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 storybooklatest 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 命令验证一切是否正常构建 Storybooknpx nx build-storybook PROJECT_NAME以及本地启动 Storybooknpx nx storybook PROJECT_NAME将PROJECT_NAME替换为你的实际项目名。如果构建与启动均无报错且控制台未出现上述失败日志即可确认迁移成功。自动化场景--autoAcceptAllPrompts 一键全自动迁移如果你希望在 CI 环境或脚本中运行迁移或者确定要接受所有提示可以加上--autoAcceptAllPrompts标志自动回答所有 Storybook CLI 提示npx nx g nx/storybook:migrate-9 --autoAcceptAllPrompts该标志的实际效果在 calling-storybook-cli.ts 中有两处体现升级阶段会将命令变为storybooklatest upgrade --yesautomigrate 阶段则会在每个storybook automigrate --config-dir ...命令后追加--yes。需要注意的是即使加上该标志Storybook CLI 可能仍会就个别事项向你提问但大部分情况下整个迁移套件会在无人值守的情况下顺畅跑完。手动分步迁移--onlyShowListOfCommands如果你希望以受控的方式逐步执行迁移可以先用--onlyShowListOfCommands让生成器只打印所需命令清单而不对代码做任何修改npx nx g nx/storybook:migrate-9 --onlyShowListOfCommands该模式对应源码中的onlyShowGuide函数它仅向终端输出一段 Storybook 9 Migration Guide 文本列出待执行命令后立即返回绝不触碰工作区文件。本质上手动迁移的完整流程如下查看命令清单运行npx nx g nx/storybook:migrate-9 --onlyShowListOfCommands生成器会列出针对你工作区每个 Storybook 项目定制的命令升级 Storybook 包执行npx storybooklatest upgrade逐个项目运行 automigrate针对清单中列出的每个项目执行对应的storybook automigrate --config-dir configDir命令使用 yarn 时命令中的storybooklatest会替换为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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/12 16:18:48 · 阅读 1.2k Nx 迁移 Storybook 9 完全指南：使用 @nx/storybook:migrate-9 生成器自动升级你的 Nx 工作区
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 的实现可以看出生成器的核心执行顺序为校验版本调用assertSupportedStorybookVersion实现见 assert-supported-storybook-version.ts基于 versions.ts 中定义的minSupportedStorybookVersion 8.0.0断言当前工作区支持的 Storybook 最低版本。检查是否安装了 Storybook通过checkStorybookInstalled检查根package.json中是否同时声明了storybook与nx/storybook依赖。如果未安装生成器会直接提示 No Storybook packages installed 并退出不做任何改动。扫描所有 Storybook 项目通过getAllStorybookInfo见 helper-functions.ts递归扫描工作区中所有.storybook/main.{ts,js,cjs,mts,mjs,cts}文件反向推导出每个项目的configDir与项目名依据项目根目录下的package.json/project.json中的name字段。升级依赖默认调用callUpgrade执行storybooklatest upgrade将所有storybook/*包升级到最新版本。自动迁移配置对每个 Storybook 项目依次执行storybook automigrate --config-dir configDir收集成功/失败的项目列表。输出结果通过logResult打印迁移完成总结并在工作区根目录生成storybook-migration-summary.md摘要文件。生成器的完整选项nx/storybook:migrate-9支持四个可选项定义于 schema.json对应 TypeScript 类型见 schema.d.ts选项类型默认值说明autoAcceptAllPromptsbooleanfalse自动回答是给 Storybook CLI 迁移脚本提出的所有交互式提示onlyShowListOfCommandsbooleanfalse只打印需要手动执行的迁移步骤清单不会对代码做任何修改noUpgradebooleanfalse跳过 Storybook 包升级步骤。仅当你已经处于 9.x 且不希望重新安装依赖时使用versionTagstringlatest要使用的 Storybook 版本标签latest表示最新稳定版next表示最新测试版枚举值限定为latest/next其中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 storybooklatest 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 命令验证一切是否正常构建 Storybooknpx nx build-storybook PROJECT_NAME以及本地启动 Storybooknpx nx storybook PROJECT_NAME将PROJECT_NAME替换为你的实际项目名。如果构建与启动均无报错且控制台未出现上述失败日志即可确认迁移成功。自动化场景--autoAcceptAllPrompts 一键全自动迁移如果你希望在 CI 环境或脚本中运行迁移或者确定要接受所有提示可以加上--autoAcceptAllPrompts标志自动回答所有 Storybook CLI 提示npx nx g nx/storybook:migrate-9 --autoAcceptAllPrompts该标志的实际效果在 calling-storybook-cli.ts 中有两处体现升级阶段会将命令变为storybooklatest upgrade --yesautomigrate 阶段则会在每个storybook automigrate --config-dir ...命令后追加--yes。需要注意的是即使加上该标志Storybook CLI 可能仍会就个别事项向你提问但大部分情况下整个迁移套件会在无人值守的情况下顺畅跑完。手动分步迁移--onlyShowListOfCommands如果你希望以受控的方式逐步执行迁移可以先用--onlyShowListOfCommands让生成器只打印所需命令清单而不对代码做任何修改npx nx g nx/storybook:migrate-9 --onlyShowListOfCommands该模式对应源码中的onlyShowGuide函数它仅向终端输出一段 Storybook 9 Migration Guide 文本列出待执行命令后立即返回绝不触碰工作区文件。本质上手动迁移的完整流程如下查看命令清单运行npx nx g nx/storybook:migrate-9 --onlyShowListOfCommands生成器会列出针对你工作区每个 Storybook 项目定制的命令升级 Storybook 包执行npx storybooklatest upgrade逐个项目运行 automigrate针对清单中列出的每个项目执行对应的storybook automigrate --config-dir configDir命令使用 yarn 时命令中的storybooklatest会替换为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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考