Storybook Canary 发布机制从 GitHub Actions 触发、版本命名到 npm 验证的完整流程【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook本文以 Storybook 仓库中的 agent 技能文档 .agents/skills/canary/SKILL.md 为主体结合其背后真实落地的 GitHub Actions 工作流 .github/workflows/publish.yml 与发布脚本 scripts/release/version.ts、scripts/release/publish.ts完整讲清 Storybook 的 PR 金丝雀canary发布机制如何用一条命令把某个 PR 构建并发布成带canarytag 的 npm 预发布版本、版本号0.0.0-pr-PR_NUMBER-sha-SHORT_SHA是如何生成并写回 PR 描述的以及拿到版本后如何用npx storybook版本 sandbox/upgrade在沙箱或既有项目中实际验证。读完后你既能照着操作触发一次 canary 发布也能理解其工作流与脚本层的调用链。触发 canary 发布canary 发布是 Storybook 维护者为某个尚未合并的 PR 生成一个可安装的 npm 预发布版本的机制构建该 PR 分支的代码、以固定格式的版本号发布到 npm 并打上canarydist-tag同时把具体版本号写回 PR 描述方便其他人在合并前试用该 PR 的改动。触发方式是直接通过 GitHub CLI 派发publish.yml工作流并传入 PR 编号gh workflow run --repo storybookjs/storybook publish.yml --field prPR_NUMBER例如为 PR #33526 触发一次 canary 发布即执行gh workflow run --repo storybookjs/storybook publish.yml --field pr33526从 publish.yml 的on:配置可以看到该工作流同时服务两条链路正式版本发布由 push 到latest-release或next-release分支触发走publish-normaljobcanary 发布由workflow_dispatch手动派发包括gh workflow run命令触发要求inputs.pr非空且inputs.skip_publish ! true此时运行publish-canaryjob。pr输入项的描述也明确标注了 CANARY RELEASES ONLY。另外工作流顶层配置了concurrency分组canary 运行按workflow PR 编号分组并允许取消进行中的旧运行这意味着同一个 PR 再次触发 canary 时新的运行会取代旧的运行避免两个构建互相踩踏而 release 分支的正式发布则按分支名分组且从不取消。版本号的命名规则canary 版本遵循一个可预测的结构0.0.0-pr-PR_NUMBER-sha-SHORT_SHAPR_NUMBERPR 编号例如33526SHORT_SHA该 PR 最新 commit SHA 的前 8 位例如a2e09fa2。以 PR #33526、commita2e09fa284a...为例对应的 canary 版本就是0.0.0-pr-33526-sha-a2e09fa2。由于规则完全确定只要你知道 PR 编号和该 PR 上最新 commit 的 SHA就可以自行拼出版本号无需等待工作流反馈。这个版本号并非凭空拼出来工作流 publish.yml 的publish-canaryjob 中有明确的推导与落盘步骤拉取 PR 信息调用gh pr view拿到headRefOidPR 最新 commit 的完整 SHA、源分支名、源仓库等信息并用cut -c 1-8截取前 8 位作为shortSha如果 PR 来自 forkcheckout 时会显式指向 fork 仓库的对应 SHA。设定精确版本在scripts/目录下执行yarn release:version --exact 0.0.0-pr-$PR_NUMBER-sha-$SHORT_SHA --verbose该命令映射到 scripts/package.json 中的jiti ./release/version.ts。从 scripts/release/version.ts 的源码看--exact选项会跳过基于semver.inc的常规递增逻辑直接把给定版本作为下一个版本源码中对--exact值有 semver 合法性校验并要求它与--release-type二选一。随后run函数会更新code/package.json的version字段即 monorepo 的总版本替换 code/core/src/manager-api/version.ts 与 code/core/src/common/versions.ts 中硬编码的版本常量遍历 monorepo 中所有 workspace 包逐个把各自package.json的version改为新版本执行yarn install --modeupdate-lockfile同步锁文件。也就是说一次 canary 版本设定会对整个 monorepo 的所有包做统一改版本保证后续发布的所有包版本号一致。此外在 GitHub Actions 环境中该脚本还会通过setOutput输出current-version/next-version供工作流后续步骤例如 PR 描述替换引用。构建并发布到 npm版本设定完成后工作流在scripts/目录执行yarn release:publish --tag canary --verbose对应实现是 scripts/release/publish.ts。从源码看publish命令的执行过程为幂等检查先读取code/package.json当前版本调用 npm registry 检查哪些包在该版本下尚未发布若全部已发布则直接跳过避免重复发布。构建全部包执行yarn task --taskcompile --start-fromcompile --no-link完成 monorepo 所有包的编译。并行 npm publish最终发布命令是yarn workspaces foreach --all --parallel --no-private --includepkg ... npm publish --provenance --tolerate-republish --tag canary其中--provenance利用 GitHub OIDC工作流为此配置了id-token: write权限为每个 tarball 附带 npm provenance 元数据--tag canary即 SKILL.md 中提到的发布到 npm 时带canarytag这一步--tolerate-republish让重发同一版本不视为致命错误。带重试的稳健性处理脚本最多重试 3 次。若某次发布部分成功npm 已接受部分包它会解析输出识别已被 registry 接受的包、只对尚未可见的包重试并在等待 registry 同步15 秒轮询一次最长 15 分钟期间不覆盖已暂存的版本防止 staged 版本导致的 409 冲突。发布结果写回 PR 描述发布成功后工作流会调用ivangabriele/find-and-replace-pull-request-body这个 action在 PR 描述中查找 HTML 注释占位符!-- CANARY_RELEASE_SECTION --并整段替换为发布报告。替换内容形如This pull request has been released as version0.0.0-pr-33365-sha-b6656566后面还附带一段可折叠的详细信息表格包含发布的版本号附 npm 页面链接、触发者、源仓库、分支、commit、触发时间与 Unix 时间戳、以及本次 workflow run 的链接。因此发布后的第一个动作就是查看 PR 描述从中拿到精确的版本号。如果发布失败工作流的兜底步骤会在该 PR 下用gh pr comment留一条失败评论附上触发者和失败的 workflow run 链接便于追溯。验证 canary 版本拿到 PR 描述中的版本号后有两种验证方式均出自 SKILL.md 的 After publishing 一节方式一新建沙箱验证。用指定版本直接创建一个 Storybook 沙箱项目npx storybookVERSION_FROM_PR sandbox在 Storybook CLI 的实现 code/lib/cli-storybook/src/bin/run.ts 中sandbox被注册为command(sandbox [filterValue])描述为 Create a sandbox from a set of possible templates会从内置模板集合中创建一个最小可运行的 Storybook 工程适合快速跑通验证 canary 版本的安装与启动是否正常。方式二升级既有项目验证。在一个已存在的 Storybook 项目里升级全部 Storybook 相关依赖到该 canary 版本npx storybookVERSION_FROM_PR upgrade同一 CLI 入口中upgrade命令支持-f/--force跳过 autoblocker 强制升级与-n/--dry-run只做检查不安装等选项适合在升级 canary 版本前先用 dry-run 预演依赖变更。需要说明的是0.0.0-pr-...这类版本带 prerelease 语义npm 的^/~范围解析一般不会自动命中它因此必须显式写全版本号来安装或升级。前提条件与权限要求SKILL.md 列出的触发前提与源码实现可以一一对应要求对应实现必须拥有storybookjs/storybook仓库的admin 权限publish.yml 中publish-canaryjob 的第一步使用check-actor-permissions-action校验触发者权限为admin不满足即失败PR 必须存在且处于 open 状态Get pull request information步骤通过gh pr view拉取 PR 的headRefOid等字段PR 不存在或已合并会导致该步骤失败ghCLI 已登录触发命令本身就是gh workflow run需要本地gh完成认证才有权限派发 workflow工作流运行需要发布凭据job 声明contents: read、pull-requests: write、id-token: writenpm provenance 所需并使用Releaseenvironment监控进度与排障触发后可以到仓库的 Actions 页面查看publish.yml工作流的运行状态对应的定义文件即 .github/workflows/publish.yml。排障时建议按以下顺序核对触发者权限Fail if triggering actor is not administrator步骤是否通过——这是最常见的失败原因普通贡献者无法触发 canary 发布SKILL.md 中也提示core team members can create a new canary release需要 canary 版本时应联系storybookjs/core团队。PR 信息解析确认gh pr view能否取到headRefOidPR 号是否正确、是否仍处于 open 状态。版本设定与发布步骤yarn release:version --exact ...与yarn release:publish --tag canary的日志注意 publish 脚本对部分失败包的重试输出Still missing ... Retrying publish for those packages only。失败评论若整个 job 失败PR 下会自动出现一条包含 workflow run 链接的评论可直接跳转到失败日志。与正式版本发布的关系canary 发布与正式版本发布共用同一个工作流但走不同的 job正式版本由 push 到latest-release对应main或next-release对应next分支触发publish-normaljob版本号来自code/package.json的当前值dist-tag 按是否 prerelease 决定为latest或next并额外承担创建 GitHub Release、合并回主干、Sentry 注册等发布后事务canary 发布则只面向单个 PR版本固定为0.0.0-pr-*结构tag 恒为canary不做 GitHub Release 等正式发布事务。理解这一分界有助于把 canary 版本定位为合并前的临时试用渠道而非可长期依赖的依赖版本。【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考