vinext 仓库的 Changesets 发布流水线:自动 changelog、beta 预发布与 SHA 提交覆盖机制

原创2026-09-24 13:35:242,000 阅读
文章标签:Web框架前端构建SSR前端后端ServerlessCLI云原生开发工具

vinext 仓库的 Changesets 发布流水线:自动 changelog、beta 预发布与 SHA 提交覆盖机制

本文以 vinext 仓库根目录下 .changeset/README.md 为骨架,结合仓库内的发布脚本、CI 工作流与真实 changeset 文件,完整讲解这套「Conventional Commits → 自动 changeset → Version PR → npm 发布」的版本管理方案。读完你将掌握:如何在 CI 中从提交信息自动生成 changeset、如何用 beta 预发布模式发布 1.0.0-beta.x 并让 npm install vinext@beta 可用、以及如何用 .changeset/<sha>.md 追溯性修正一个已经合并的提交的版本号与 changelog 条目。

一、Changesets:多包仓库的版本与发布工具

.changeset 目录由 @changesets/cli 自动生成。这是一款面向多包(multi-package)仓库与单包仓库的版本管理、changelog 生成与发布工具,核心思路是:每次变更先用一份「changeset」描述会影响哪些包、升到什么版本号,再由工具集中消费这些 changeset,统一生成 Version PR、改写各包的 package.json 版本与 CHANGELOG.md,最后执行发布。

在 vinext 仓库中,这一流程被进一步定制:

对应地,根目录 package.json 中声明了 @changesets/cli 依赖,并提供了 changeset 脚本入口(pnpm changeset 或仓库统一的 vp exec changeset)。

二、目录与配置:.changeset/config.json 与 pre.json

仓库的 .changeset 目录实际包含三类文件,在 .changeset/ 下均可找到实例:

  1. 配置与状态文件:config.json 与 pre.json;
  2. 人工提交的 changeset:以 形容词-名词-动词.md 风格随机命名,例如 enter-v1-beta.md(该文件用 major 声明了首次 1.0 beta 发布);
  3. CI 自动生成的 changeset:统一以 auto- 前缀命名,例如 auto-_vinext_cloudflare_1.0.0-beta.8-ccc7c20.md。

config.json 关键字段

.changeset/config.json 的配置要点如下:

字段 当前值 含义
changelog @changesets/cli/changelog 使用 Changesets 默认 changelog 生成器(仓库随后会用 scripts/version.mts 重写为按类型分组的形式)
commit false 不自动生成版本提交信息
access public 发布到 npm 公共源
baseBranch main 以 main 为基准分支
updateInternalDependencies patch 内部依赖的最低更新级别
bumpVersionsWithWorkspaceProtocolOnly true 仅对使用 workspace 协议的依赖执行版本联动

pre.json:预发布模式的现场状态

.changeset/pre.json 记录了 mode: "pre"、tag: "beta",以及进入预发布时各包的 initialVersions(如 vinext: 0.2.1、@vinext/cloudflare: 0.2.1、create-vinext-app: 0.2.0)。从 packages/vinext/CHANGELOG.md 可以看到,vinext 当前已推进到 1.0.0-beta.11,说明自进入 beta 模式以来已累积了多个迭代版本。

三、CI 自动生成 changeset:create-changeset.mts 与 release.yml

3.1 整体流程

根据 .github/workflows/release.yml,每次向 main 推送时,单个 Release 工作流依次执行:

  1. node scripts/create-changeset.mts 从 Conventional Commits 生成 auto-*.md changeset,只写入 CI 工作树(working tree),从不提交到 main——它们存在的唯一目的,就是供 changesets/action 消费进持续滚动维护的 "Version Packages" PR;
  2. changesets/action 接管其余工作:只要还有 changeset 存在,就维护滚动更新的 Version PR;当 Version PR 刚合并、changeset 为空时,则执行发布(通过 npm OIDC trusted publishing + provenance 签名),并创建 git tag 与 GitHub Release。

工作流中的关键定制点:version: 阶段运行 node scripts/version.mts(即 changeset version 外加 Contributors 列表),publish: 阶段运行 node scripts/publish.mts(仅发布有变更的包,并让预发布版本成为默认安装)。

3.2 提交类型到版本号的映射

scripts/create-changeset.mts 中定义了核心映射表 TYPE_BUMP:

Conventional Commit 类型 对应 bump
feat minor
fix / perf / revert patch
refactor / docs / test / ci / build / chore / style 不发布(null)

同时,parseBumpFromSubject 会识别两种特殊情况:主题中含 !(如 feat!:)或提交正文含 BREAKING CHANGE: 脚注时,直接判定为 major,覆盖上表结果。affectedPackages 则通过"最长目录优先匹配"的规则,把每个变更文件归属到对应包——一个提交只会为其实际改动的包产生 bump。

3.3 发布与生成的互斥保护

由于自动 changeset 每次推送都会从「最近一次发布 tag」到 HEAD 全量重算(保证幂等、避免在 main 上累积 changeset),刚合并 Version PR 后若立即重新生成,就会把刚发布的提交再次捡起来、重新打开 Version PR。为此 decideGeneration 实现了一个保护:只要任一包的 package.json 版本高于其最近 tag(说明"已版本化、等待发布"),整个工作区就停止生成(hasPendingPublish),让 changesets/action 直接进入发布而非重新开 PR。这也解释了为什么发布触发刚好在 Version PR 合并后发生。

3.4 生成的 changeset 长什么样

一个自动生成的 changeset 由 frontmatter(各包的 bump 声明)+ 正文(以 - 开头的提交摘要)组成,例如 auto-_vinext_cloudflare_1.0.0-beta.8-ccc7c20.md:

---
"@cloudflare/workers-response-store": minor
"@vinext/cloudflare": major
"vinext": major
---

- feat(response-store): read response metadata from R2 (#3339)
- fix(cache): bypass shared lookup for force-dynamic routes (#3346)
- refactor(cloudflare): route traffic-aware warming through standard prewarming (#3338)
- ...

文件名 auto-<起始引用>-<HEAD 短哈希>.md 记录了这次 changeset 覆盖的提交区间,便于追踪。

四、beta 预发布模式:从 1.0.0-beta.0 到稳定版

仓库当前运行在 Changesets 的 prerelease 模式,pre.json 中标明 tag: "beta":

  • 进入模式:首次 Version Packages PR 会把 vinext、@vinext/cloudflare、create-vinext-app 统一发布为 1.0.0-beta.0。仓库中 enter-v1-beta.md 正是这个"入场券":
    ---
    "@vinext/cloudflare": major
    "create-vinext-app": major
    "vinext": major
    ---
    
    Release the first vinext 1.0 beta.
    
  • 迭代发布:后续每次 Version PR 递增 beta 号(1.0.0-beta.1、beta.2……),changeset publish 会把它们发布到 npm 的 beta dist-tag。此时安装预发布版用:
    npm install vinext@beta
    
  • 退出 beta:当 beta 稳定、准备转正时,运行:
    vp exec changeset pre exit
    
    并提交随之更新的 .changeset/pre.json。下一次 Version Packages PR 会移除预发布后缀,发布时切到 npm 的 latest dist-tag,成为默认安装版本。

一个实现细节:如何让 beta 版本默认可装

Changesets 在 pre 模式下会强制把 dist-tag 设为预发布名,并拒绝 --tag latest。而 vinext 希望在 beta 阶段就让 npm install vinext 默认拿到 -beta.* 版本。为此 scripts/publish.mts 实现了 withHiddenPrereleaseState:发布前把 pre.json 临时改名备份、发布后再恢复(finally 中保证即使发布失败也会还原),从而在保留已版本化的 -beta.* 版本号的同时,把它们发布到 latest tag。发布参数 publishArgs 在存在 pre.json 时追加 --tag latest。

五、手写 changeset:何时需要、怎么写

虽然 CI 会自动生成大部分 changeset,但你依然可以手写:

  • 人工提交到 main 的 .changeset/*.md 会被与自动生成的一并消费(构建 Version PR 时两者都算数);
  • 当你需要覆盖或补充提交驱动的版本号时,用:
    pnpm changeset
    # 或
    vp exec changeset
    
    添加一份手写 changeset 即可。

一个典型的手写 changeset 只有几行:frontmatter 声明各包 bump,正文写变更说明。

六、追溯性修正提交:.changeset/.md 覆盖机制

这是 .changeset/README.md 中最重要的定制功能,值得单独展开。

6.1 为什么需要它

普通手写 changeset 只能抬高 bump(Changesets 取所有声明的最大值),无法降低一个已合并提交的版本;而自动 changeset 每次推送都会从提交信息重新生成,也无法通过编辑它们来修正标签错误的提交。比如一个实际是小修复、却以 feat:(minor)合并的 PR,无法靠常规手段降级为 fix:(patch)。

6.2 做法

提交一份文件名是提交 SHA 的 changeset:.changeset/<sha>.md。发布工具链会把这个提交当作 frontmatter 中声明的 bump 处理(忽略其提交信息暗示的 bump),并把 changeset 正文作为该提交的 changelog 条目——同时覆盖 semver bump、changelog 分组和消息文本。

例如,要把一个以 feat: 合并(本会升 minor)的 PR 降级为 fix:(patch)并改写文案:

---
"vinext": patch
---

correct interception route matching for sibling segments (#1234)

保存为 .changeset/6005541c0a1b2c3d.md(使用完整 SHA,7+ 位前缀也可)。随后该条目会以 - correct interception route matching for sibling segments (#1234) 出现在 Bug Fixes 分组下。

6.3 frontmatter bump 与 changelog 分组的映射

Frontmatter bump 被视作 Changelog 分组
patch fix Bug Fixes
minor feat Features
major feat! Features
(无包 / 空) chore (丢弃)

因此,一份空白的、不带任何包声明的 SHA 命名 changeset,会直接抑制(suppress)该提交:不产生发布,也不进入 changelog。这在源码中有明确对应:shaFromChangesetFilename 识别 7–40 位十六进制字符的 changeset 文件名;bumpToOverride 将 frontmatter bump 映射回 conventional 类型;loadOverrides 对无包声明的文件按 chore 处理。

6.4 注意事项

  • 它是真正的 changeset:changesets/action 会消费它参与 bump 计算,并在发布时删除它,因此覆盖不会累积,无需手动清理;
  • 正文成为 changelog 条目:以纯 bullet 渲染(替换提交信息的描述、scope 等全部内容)。建议保持单行、小写开头、带 PR 引用,与其它条目风格一致;若留空正文,则保留原提交信息的描述、仅重新分类类型;
  • 声明与提交实际影响的相同包,并写上你想要的 bump;
  • scripts/create-changeset.mts(负责 bump 计算)与 scripts/version.mts(负责 changelog 分组与消息)都识别该机制,均以文件名中的 SHA 为键。applyOverrides 会同时清空提交正文中的 BREAKING CHANGE: 脚注,避免它重新抬高 bump。

七、changelog 生成:按类型分组与 Contributors 列表

发布链路的另一处定制在 scripts/version.mts:运行完 changeset version 后,脚本会重写每个被 bump 包的最新 changelog 段落:

  • 按 Conventional Commit 类型分组为 ### Features / ### Bug Fixes / ### Performance / ### Reverts,每个类型内,若某 scope(如 app-router、cache)达到 3 条以上条目,则单独开 #### <Area> 子分组(scope 会经 humanizeArea 转成可读区域名,并特判 i18n、css、ppr、rsc、cdn、ssr、api、og、url、html、cli 等缩写);
  • 追加 ### Contributors 列表:从 gh api repos/<owner>/repo/compare/<from>...HEAD 分页拉取 sha → login 映射,只统计该包自己的提交,并经 dedupeSortLogins 去重、过滤 bot([a-zA-Z0-9-] 之外的形状丢弃)后排序。

一个值得注意的细节:Contributors 用 ### 而非 ## 标题,是因为 Changesets 的 getChangelogEntry 以「## <版本号> 到下一个同级 ##」为界截取 GitHub Release 正文,若用 ## Contributors 会截断 Release 说明。

从 packages/vinext/CHANGELOG.md 的 1.0.0-beta.11 段落可以看到这套机制的成品效果:Features / Bug Fixes 分组下的 **Tracing:**、**Response Store:** 等加粗区域标签,以及底部的 Contributors 列表。

八、实战小结

把整条链路串起来,vinext 的版本发布是这样一个闭环:

  1. 开发者按 Conventional Commits 规范提交(feat:、fix:、perf: 等,必要时加 ! 或 BREAKING CHANGE: 脚注);
  2. 推送到 main 后,.github/workflows/release.yml 中的 create-changeset.mts 从上次 tag 到 HEAD 全量重算,生成仅存在于 CI 工作树的 auto-*.md;
  3. changesets/action 将这些 changeset(连同人工提交的)滚动进 Version Packages PR;若恰好刚合并完 Version PR,则改为直接发布;
  4. 发布时 scripts/publish.mts 借助临时隐藏 pre.json 的技巧,把 1.0.0-beta.x 发布到 latest tag(beta 阶段即可默认安装);scripts/version.mts 负责把 changelog 重写为分组 + Contributors 的成品;
  5. 若某提交标签错误,提交 .changeset/<sha>.md 即可追溯性修正 bump 与 changelog,且发布后自动清理,不产生累积。

这套设计的核心价值在于:版本号与 changelog 不再依赖人工维护,全部由提交信息驱动;同时保留了两处可控的"人肉闸门"——手写 changeset 覆盖,以及 SHA 命名 changeset 的追溯修正,兼顾了自动化与精确性。

登录后查看全文
vinext