Storybook Upgrade 命令实战用 npx storybook upgrade 安全升级所有 Storybook 包【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook这篇指南聚焦 Storybook 仓库中storybook upgrade命令的完整使用方式与底层实现如何把项目中的全部storybook/*包一次性升级到 canary、stable 或指定 release 版本为什么不能手动npm add各个包、为什么一次只能跨一个大版本以及该命令在源码层面如何执行版本校验、依赖更新、自动迁移automigrations、依赖安装与健康检查doctor。读完后你能独立完成 Storybook 项目的版本升级流程并能读懂升级过程中的每一步输出与失败原因。命令用途与适用场景Storybook 仓库内置了一个面向 AI Agent 的技能文档 storybook-upgrade它定义了将项目中所有 Storybook 包升级到指定版本的标准操作。该技能的核心定位是在本仓库之外的下游项目上验证 Storybook 变更在一个下游应用中 QA 某个 Storybook PR 产出的 canary 构建在外部项目中复现或验证某个 bug。对应的标准命令只有一行npx storybookVERSION upgrade三种典型用法均继承自技能文档的 Examples 小节# 升级到 canary 版本由 PR 构建产物 npx storybook0.0.0-pr-33526-sha-a2e09fa2 upgrade # 升级到最新稳定版 npx storybooklatest upgrade # 升级到某个具体 release npx storybook8.5.0 upgrade这里的关键点是npx 指定的版本号决定了升级目标npx storybooklatest会拉取最新的 CLI 包并在你的项目里执行其upgrade子命令目标版本就是这个 CLI 包自身携带的versions.storybook。因此升级 8.5.0 时执行的正是 8.5.0 版本的 CLI而不是本地已经安装的旧版本 CLI。命令的完整参数来自 CLI 源码技能文档只展示了最基本的调用形式但 CLI 源码中注册了更丰富的选项。以下参数全部定义在 run.ts 的command(upgrade)注册段中参数说明--package-manager type强制指定安装依赖使用的包管理器npm / yarn / pnpm 等-y, --yes跳过交互提示全部采用默认答案--features list逗号分隔的实验性 feature flag 列表通过 automigrations 在升级过程中启用-f, --force强制升级跳过 autoblockers自动拦截检查-n, --dry-run只检查可升级内容不真正安装-s, --skip-check跳过 postinstall 版本与 automigration 检查--skip-automigrations完全跳过 automigrations仅更新包版本并安装-c, --config-dir dir-name...指定一个或多个 Storybook 配置目录支持 monorepo 多项目此外所有子命令共享一组全局选项同样在 run.ts 中定义--disable-telemetry可用环境变量STORYBOOK_DISABLE_TELEMETRY控制、--debug、--enable-crash-reports、--logfile [path]、--loglevel trace \| debug \| info \| warn \| error \| silent。需要注意两个约束均来自源码中的显式检查--features与--skip-automigrations不能组合使用因为--features本身就是通过 automigrations 机制生效的组合时 upgrade.ts 会直接抛出HandledError若命令执行失败日志会先写入文件默认debug-storybook.log可由--logfile指定路径再退出方便排查自动化迁移失败的具体原因。升级流程的源码级拆解技能文档概括升级命令会做四件事检测项目中所有storybook/*包、把它们全部升到目标版本、自动处理 peer 依赖、兼容 npm/yarn/pnpm。upgrade.ts 中的upgrade(options)函数给出了完整实现实际调用链比文档描述更细收集项目getProjectsgetProjects会扫描出所有 Storybook 项目monorepo 下可能有多个配置目录并区分allProjects与用户实际选中的selectedProjects多项目时会逐行打印每个项目的升级方向beforeVersion - currentCLIVersion。运行 autoblockers自动拦截processAutoblockerResults检查是否存在阻断条件如大版本跳跃、降级发现阻断时打印 Blockers detected 并中止除非使用--force。版本合法性校验如果目标版本低于当前已安装版本lt(project.currentCLIVersion, project.beforeVersion)抛出UpgradeStorybookToLowerVersionError如果读不到当前版本抛出UpgradeStorybookUnknownCurrentVersionError。更新 package.jsonupgradeStorybookDependencies遍历每个项目把所有 Storybook 相关依赖写到目标版本dry-run时跳过此步。执行 automigrations调用runAutomigrations运行配置与代码的自动迁移修复可被--skip-automigrations跳过。安装依赖对 npm 会带force: true安装源码注释指出这是为了规避 npm 的一个已知问题yarn / pnpm 走常规安装。monorepo 去重在非 Yarn 1 的 monorepo 场景中命令会提示并可选执行dedupe避免同一 Storybook 包存在多个物理副本。配置延迟安装的 addons某些 automigration 会引入新 addon 但把 postinstall 配置推迟到依赖安装完成之后configureDeferredAddons保证 先装后配 的顺序。运行 doctor 健康检查runMultiProjectDoctordisplayDoctorResults对每个项目输出诊断最终由logUpgradeResults汇总为三类结果成功升级、升级失败automigration 失败或 check 失败、无需迁移。从源码结构看升级的最终判定是存在成功修复且无失败项才算成功若所有项目 doctor 结果均为 healthy会输出 Your project(s) have been upgraded successfully! 否则提示存在需要人工关注的问题。为什么必须一次只升一个大版本技能文档中最强调的一条规则是ALWAYS upgrade only 1 major version at a time!例如 8.x → 9.x → 10.x → 10 的 canary绝不允许从 8.x 直接跳到 10.x。这条规则不是口头建议而是由 autoblocker 机制在源码中强制执行的。block-major-version.ts 中定义了major-version-gap拦截器validateVersionTransition(currentVersion, targetVersion)比较当前版本与目标版本若当前版本更高判定为downgrade不支持降级若目标 major 与当前 major 之差大于 1判定为gap-too-large跳跃过大major 为 0 的版本如0.0.0-pr-*这类 canary不参与拦截。命中拦截后CLI 会打印明确指引例如大版本跳跃时会直接给出下一步该执行的命令npx storybooknextMajor upgrade也就是说如果你从 8.x 直接执行npx storybook10 upgrade命令会被阻断并提示你先用 9 的 major 版本过渡一次。这就是 8.x → 9.x → 10.x 链式升级在工具层的落地方式其目的正是让每一级 major 的破坏性变更和 automigrations 都能被独立应用与验证。为什么不能手动 npm add Storybook 包技能文档给出了另一条硬性禁令DO NOTmanually install storybook packages withnpm add/yarn add/pnpm add。Always usenpx storybookversion upgradeto ensure all packages stay in sync.原因在源码中可以得到印证Storybook 由大量同版本的包组成core、renderer、framework、addons 等upgrade命令通过upgradeStorybookDependencies统一解析并更新所有相关依赖保证它们指向同一版本线而手动逐个add很容易造成版本错位。仓库甚至内置了版本一致性检查逻辑checkVersionConsistency位于 upgrade.ts通过npm ls输出解析所有storybook/*包版本发现同一项目里存在多个版本时会打印 Found N outdated packages 的告警提示你确认包已对齐upgrade.test.ts 中的getStorybookVersion用例覆盖了带├─┬前缀、dedupe 行、peer dep 报错行等各种npm ls输出格式的解析。从 upgrade.test.ts 的generateUpgradeSpecs用例还可以看到一个细节升级时依赖声明中的版本修饰符会被尽量保留~8.0.0→~9.0.0、^8.0.0→^9.0.0、8.0.0→9.0.0而*、workspace:*这类无法保留修饰符的写法会被归一为精确版本。这解释了为什么用统一命令升级比手工编辑 package.json 更安全——它同时处理了 peer 依赖与版本区间语义。验证升级结果doctor 与 automigration 摘要升级结束时命令会做两件事帮你确认状态automigration 摘要logUpgradeResults按项目输出 Successfully upgraded / Failed to upgrade / No applicable migrations 三类清单并附上每个已执行 automigration 的说明链接方便对照迁移指南理解每项变更doctor 诊断runMultiProjectDoctor检查已知问题并给出修复建议doctor 发现 issues 时会自动启用日志落盘logTracker.enableLogWriting()把详细调试信息写入日志文件。如果升级后仍有异常推荐的操作顺序是查看命令输出的日志文件路径 → 定位失败的 automigration 或 doctor 项 → 按提示单独重跑对应修复storybook automigrate [fixId]命令同样在 run.ts 中注册支持--list查看全部可用迁移、--dry-run只做检查。适用前提与限制该命令面向外部应用、复现工程或测试项目使用技能文档明确说它是 mainly for validating Storybook changes outside this repositoryStorybook 仓库自身作为 monorepo 的内部版本管理走的是另一套发布流程不应在仓库内直接跑此命令目标版本由 npx 中指定的storybookCLI 版本决定因此升级 canary 时使用的是 PR 构建产物的 tag形如0.0.0-pr-XXXXX-sha-XXXXXXX降级不被支持源码层面直接报错跨大版本跳跃会被 autoblocker 拦截--force可以跳过 autoblockers 但意味着你自行承担多级变更叠加的风险--dry-run只读不写适合升级前先确认影响范围--skip-install/--skip-check等选项面向自动化流水线场景手动升级时建议保留默认检查以获得完整诊断。参考路径技能文档本文骨架来源.agents/skills/storybook-upgrade/SKILL.md升级命令实现code/lib/cli-storybook/src/upgrade.ts命令注册与参数定义code/lib/cli-storybook/src/bin/run.ts大版本拦截器code/lib/cli-storybook/src/autoblock/block-major-version.ts单元测试code/lib/cli-storybook/src/upgrade.test.ts升级相关的 Agent 评测用例agent-eval/evals/821-upgrade-from-sb9、agent-eval/evals/822-upgrade-from-stable、agent-eval/evals/823-setup-outdated-storybook【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考