assistant-ui 仓库的 Changesets 版本发布体系:从 .changeset 目录到 npm 自动发布

原创2026-10-10 19:16:591,452 阅读
文章标签:前端UI组件人工智能AI 应用AI Agent移动开发

assistant-ui 仓库的 Changesets 版本发布体系:从 .changeset 目录到 npm 自动发布

本指南以仓库根目录 .changeset/README.md 为入口,讲解 Changesets 如何在 assistant-ui 这个超大型 pnpm monorepo 中驱动版本管理与 npm 发布。读完你将掌握:.changeset/ 目录与 changeset 文件的结构规范、pnpm changeset 的完整工作流、本仓库为 0.x 包定制的 semver 策略、changeset version / changeset publish 的 CI 链路,以及仓库自建的 changeset 校验脚本如何把不合规的变更拦在合并之前。

一、.changeset/README.md 讲了什么:一个自动生成的管理目录

.changeset/README.md 是 @changesets/cli 在仓库初始化时自动生成的说明文件。它明确告诉开发者三件事:

  1. .changeset/ 目录由 @changesets/cli 自动生成,该工具同时支持多包仓库(monorepo)和单包仓库(single-package repo)两种形态,用于帮助项目完成版本号(version)与发布(publish)流程;
  2. Changesets 的完整文档托管在它自己的上游仓库中;
  3. 目录里收集了「常见问题」入口,供刚接触该流程的贡献者快速上手。

这段描述虽然简短,却是整个发布体系的地图。真正支撑它的,是仓库里一系列配套的实现:.changeset/config.json(全局配置)、一批真实存在的 changeset 文件(待发布变更记录)、根目录 package.json 中的 CI 脚本、以及 scripts/check-changesets.mjs 与 scripts/check-changeset-semver.mjs 两套自建校验。下面逐层展开。

二、仓库的 Changesets 全局配置:.changeset/config.json

仓库根目录的 .changeset/config.json 是 Changesets 的行为基准,当前内容如下:

{
  "$schema": "https://unpkg.com/@changesets/config@3.0.1/schema.json",
  "changelog": [
    "@assistant-ui/x-changelog",
    {
      "repo": "assistant-ui/assistant-ui"
    }
  ],
  "access": "public",
  "format": false,
  "privatePackages": {
    "version": false
  },
  "___experimentalUnsafeOptions_WILL_CHANGE_IN_PATCH": {
    "onlyUpdatePeerDependentsWhenOutOfRange": true
  }
}

逐项解读:

配置项 当前值 含义与影响
$schema @changesets/config@3.0.1 的 schema 配置的 JSON Schema 来源,编辑器可据此获得校验与补全;@changesets/cli 在根 package.json 中被声明为 ^3.0.3,两者版本对齐
changelog <a href="https://link.gitcode.com/i/c646e7f6ae63517bb72783f3d85b3316" target="_blank">"@assistant-ui/x-changelog", { "repo": "assistant-ui/assistant-ui" }] 指定 changelog 生成器为仓库自研的 @assistant-ui/x-changelog,并传入 repo 参数;生成器实现在 [packages/x-changelog/index.mjs
access "public" 发布到 npm 时对所有包公开访问(即发布为公共包,而非受限于 npm 组织的私有包)
format false 关闭 changeset 文件的自动重排格式化,保留作者原始书写格式
privatePackages.version false 私有包("private": true)不参与版本号提升,只有公开发布的包才会被 changeset version 处理
onlyUpdatePeerDependentsWhenOutOfRange true 仅当依赖版本超出 peerDependencies 允许范围时才级联更新依赖方,减少不必要的连带 bump

其中 changelog 是配置里最值得展开的一项。仓库自研的 @assistant-ui/x-changelog 是从 @changesets/changelog-github@1.0.0 fork 而来,核心差异只有一点:把作者署名从正文前的 " Thanks @user!" 挪到首行末尾的 " (@user)",使 changelog 首行更紧凑、便于扫描(见 packages/x-changelog/index.mjs 的注释)。它还实现了两个 changelog 钩子:

  • getReleaseLine(changeset, type, options):从 changeset 的 summary 中解析 pr:、commit:、author: 前缀,分别替换为 PR 链接、commit 链接和用户链接,并把 #123 这样的 issue 引用自动链接化(linkifyIssueRefs);
  • getDependencyReleaseLine(changesets, dependenciesUpdated, options):当某个包的发布触发依赖方版本更新时,生成 - Updated dependencies [...] 段,逐行列出发布的依赖名与新版本号(dependency.name@dependency.newVersion)。

注意:x-changelog 的 getReleaseLine 在缺少 repo 配置时会直接抛错,因此 .changeset/config.json 中必须成对提供 repo 参数,这是该生成器的硬性要求。

三、changeset 文件长什么样:仓库里的真实样本

.changeset/ 目录下除 README 与 config.json 外,还存放着一批待发布的 changeset 文件(当前仓库中如 bright-ducks-sort.md、cloud-run-auth-generation.md、puny-pugs-fetch.md 等)。一个合法的 changeset 是 Markdown 文件,由两部分组成:

  1. YAML frontmatter:以 --- 分隔,列出「包名: 升级类型」映射;
  2. 正文:人类可读的变更摘要,最终会被写入对应包的 CHANGELOG.md。

仓库中的真实样本(.changeset/persist-seeded-history.md):

---
"@assistant-ui/core": patch
---

fix(core): preserve initial messages after an empty history load and persist them before the first new message

再看一个多包共用一个 changeset 的样本(.changeset/quiet-crabs-send.md):

---
"@assistant-ui/core": patch
"@assistant-ui/react": patch
"@assistant-ui/vue": patch
---

Block typing, attachments, sends, and message editing while a thread is disabled.

frontmatter 中的升级类型只有三个合法取值:patch、minor、major(另有一个内部使用的 none)。包名必须与 pnpm-workspace.yaml 声明的 workspace 包名完全一致。正文推荐带 fix(...) / feat(...) 这类约定式提交前缀,便于 changelog 阅读与检索。

3.1 校验脚本对文件格式的严格要求

仓库在 scripts/lib/changesets.mjs 中实现了对上述格式的严格解析,CI 无法解析的 changeset 会被直接拒绝:

  • frontmatter 边界:必须匹配 /^\s*---(<a href="https://link.gitcode.com/i/9b7407f042cf3b2fabbe2ca8c23b8e68" target="_blank">\s\S]*?)\r?\n\s*---(\s*(?:\n|$)[\s\S]*)/,即开头的 --- 与结尾的 --- 之间是 YAML 块(readChangesetSource,[scripts/lib/changesets.mjs);
  • 行格式:每条「包名: 类型」必须是 YAML block-mapping 行——包名不能以 YAML 指示符开头(也不能是 - / ? 开头的序列/复杂键),冒号后必须有空格或 Tab,且缩进只能用空格(用 Tab 缩进会被判为非法,见 parseReleaseLine 的正则,scripts/lib/changesets.mjs);
  • 包名唯一:同一个 changeset 里一个包只能出现一次,重复命名会报错(readChangesetReleases,scripts/lib/changesets.mjs);
  • 缩进一致:同一 changeset 内所有 release 行的缩进必须一致,否则视为错误。

从这些校验细节可以看出:虽然 changeset 只是"Markdown + YAML",但为了与 @changesets/parse 的行为严格对齐,仓库在 CI 里不依赖 node_modules 就完成了等价解析(文件头注释明确说明这是 mdRegex 的拷贝,scripts/lib/changesets.mjs)。

四、实战工作流:从 pnpm changeset 到发布

4.1 创建 changeset

在 assistant-ui 仓库根目录执行:

pnpm changeset

@changesets/cli 会检测自上次发布以来哪些包发生了变更,并交互式地引导你完成三件事:

  1. 选择要发布的包(支持多选,一次性可为一个以上包记录变更);
  2. 选择升级类型(patch / minor / major);
  3. 填写变更描述。

完成后会在 .changeset/ 下生成一个新的随机命名(如 bright-ducks-sort.md)Markdown 文件,格式与第三节的样本一致,之后把它随代码一起提交。

4.2 提交规范与 CI 强制校验

仓库 CONTRIBUTING.md 明确:每个改了发布包的 PR 都必须附带 changeset,否则变更不会发布到 npm。这条规则由两套自建脚本强制落地(定义于根 package.json):

  • changesets:check → node scripts/check-changesets.mjs:扫描 .changeset/ 下所有 .md 文件(跳过 README.md),报告「changeset version 无法解析的文件」以及「命名了不可发布包」的问题。所谓不可发布包包括:不存在的 workspace 包(拼错或改名)、私有包(private: true 且 privatePackages.version: false)、与已发布包混在同一条 changeset 中的 ignore 包、没有 version 字段却与已发布包共存的包(见 findUnreleasablePackages,scripts/check-changesets.mjs)。任一类错误都会令脚本以非零状态退出;
  • changeset-semver:check → node scripts/check-changeset-semver.mjs:为 0.x 包定制 semver 门槛,防止破坏依赖范围的 bump 进入发布流程。

4.3 一键版本化与发布

变更合并到 main 后,CI 看到 .changeset/ 中有待处理变更,会自动创建 "update versions" PR,其中执行:

changeset version && pnpm install --no-frozen-lockfile --lockfile-only

即根 package.json 中的 ci:version 脚本。changeset version 会完成三件事:消费掉 .changeset/*.md(删除已处理的 changeset 文件)、按 frontmatter 声明的类型提升各包 package.json 的 version 字段、用 x-changelog 生成器重写各包 CHANGELOG.md。随后 pnpm install --lockfile-only 同步 lockfile,保证版本号变更反映到 pnpm-lock.yaml。

该 PR 合并后,CI 执行发布脚本(package.json):

turbo build --filter="./packages/*" && changeset publish

先用 turbo 并行构建 packages/ 下所有包,再调用 changeset publish 把本次 release 涉及的包逐一发布到 npm(配合配置中的 "access": "public")。

4.4 变更包校验:--changed-packages 模式

check-changesets.mjs 还支持按提交范围校验:

node scripts/check-changesets.mjs --changed-packages

该模式要求设置 BASE_SHA 与 HEAD_SHA 环境变量,然后通过 git diff 找出 fork point 与 head 之间改动的文件,判定「改了发布包却没有对应 changeset」的 PR 并直接失败(见 runChangedPackageCheck 与 mainChangedPackages,scripts/check-changesets.mjs)。其判定规则值得一提:

  • 包内 package.json、dist/、测试目录、测试文件、顶层 Markdown 的改动不计入「需要 changeset」;
  • 但 package.json 中影响消费者安装的字段(如 exports、files、bin、sideEffects、engines、publishConfig、peerDependenciesMeta、安装钩子、第三方依赖范围等)一旦变化,就需要 changeset 点名该包;
  • 反之,纯 version bump、devDependencies 修改、消费者不会运行的 scripts 条目、以及 workspace 依赖的范围调整(仅改范围不改名字)都由 release 流程自行处理,无需贡献者写 changeset。

五、0.x 时代的 semver 策略:为什么"几乎永远选 patch"

assistant-ui 的大多数包仍处于 0.x 版本(如 0.12.15)。在 semver 中,caret 范围 ^ 对 0.x 的处理与 1.x+ 完全不同:

范围 允许的升级 示例
^1.3.12 任意 minor 或 patch(>=1.3.12 <2.0.0) 1.4.0 可以
^0.12.15 仅 patch(>=0.12.15 <0.13.0) 0.13.0 超出范围

也就是说,对 0.x 包做一次 minor bump,会立刻破坏所有依赖它的包的 caret 范围,迫使 changesets 沿整个依赖图级联产生 patch bump,造成无意义的版本波动和噪音 changelog。

因此仓库的 CONTRIBUTING.md 定下了三条硬规则:

  • patch:所有变更都选它——bug 修复、新功能、重构、新导出,一律 patch;
  • minor:仅当维护者明确要求时使用(会在整个依赖图上引发级联 patch bump);
  • major:仅用于计划内的稳定版本(1.0、2.0),未经维护者批准绝不使用。

这也解释了为什么第三节列出的仓库现存 changeset 清一色是 patch——这不是巧合,而是既定策略的执行结果。

六、边界情况:什么不需要 changeset

并非所有仓库内容变更都走 changeset,以下几点是常见的边界:

  • 不发布到 npm 的包:如 @assistant-ui/docs、@assistant-ui/shadcn-registry 这类部署在 Vercel 的应用/注册表包,无需 changeset;
  • Python 包:python/ 目录下的包不写 changeset,它们的 pyproject.toml 版本号由维护者在发布 PR 中、发布到 PyPI 前统一提升(check-changeset-semver.mjs 还会拦截"与其它包改动混在一起"的 pyproject.toml 版本修改);
  • 纯测试与顶层文档:测试文件和顶层 Markdown 的改动不计入需要 changeset 的范围。

七、写给贡献者的快速上手指南

结合以上内容,在 assistant-ui 提交一个会被发布的改动时,完整流程是:

  1. 实现改动并写测试,在本地 pnpm changeset 生成 changeset,类型优先选 patch;
  2. 提交代码与 changeset 文件,推送到 PR;
  3. CI 依次跑 changesets:check 与 changeset-semver:check:前者校验文件可解析、包名真实且可发布,后者校验 0.x 包的 bump 级别合法,任一失败 PR 即被拦截;
  4. 合并到 main 后,CI 自动开出 "update versions" PR(changeset version + lockfile 同步),合入后 turbo build + changeset publish 将新版本发布到 npm,同时各包 CHANGELOG.md 由 @assistant-ui/x-changelog 写入带 PR/commit/作者链接的条目。

整个过程从 .changeset/README.md 里短短三句话开始,背后是配置、格式校验、semver 策略、CI 脚本与自研 changelog 生成器共同组成的一条完整发布链路——理解这条链路,就能在仓库里放心地提交任何会被发布到 npm 的改动。

登录后查看全文
assistant-ui