Changesets 常见问题全解析:changeset 文件、交互式添加与版本发布机制

原创2026-09-22 20:04:081,928 阅读
文章标签:开发工具CLI

Changesets 常见问题全解析:changeset 文件、交互式添加与版本发布机制

本指南以 Changesets 官方 FAQ 为基础,系统讲解 changeset 文件的结构与语义、何时需要添加 changeset、如何通过 CLI 交互式生成 changeset、一个 PR 内多个 changeset 的堆叠用法、手动编辑与删除规则,以及 changeset version 消费并移除 changeset 的底层机制。读完本文,你将完全掌握 changeset 从创建、修改到被版本命令消费的完整生命周期。

What is a changeset?——认识 changeset 文件

changeset 本质上是一个带 YAML frontmatter 的 Markdown 文件,是 Changesets 管理版本与变更日志的最小单元。它的结构非常清晰:

  • Markdown 正文:变更摘要,将来会被写入对应包的 CHANGELOG;
  • YAML frontmatter:描述哪些包发生了变更,以及各自对应的 semver 升级类型(major / minor / patch)。

一个典型的 changeset 文件长这样:

---
"pkg-a": minor
"pkg-b": patch
---

Summary of the change

也就是说,一个 changeset 可以同时声明多个包的变更,例如 pkg-a 升 minor、pkg-b 升 patch。它回答了两个问题:改了什么(摘要),以及下次发布时版本该怎么升(frontmatter)。

从源码层面看,parse 包的 parseChangesetFile 负责解析这类文件:先用正则 /\s*---(<a href="https://link.gitcode.com/i/353abaff1124e63aea3488956db05df7" target="_blank">^]*?)\r?\n\s*---(\s*(?:\n|$)[^]*)/ 切分出 frontmatter 与摘要,再用 YAML 解析器把 frontmatter 读成"包名 → 版本类型"的映射,最后逐条校验版本类型必须是 major、minor、patch、none 之一([packages/parse/src/index.ts)。如果包名为空、版本类型缺失或非法,解析器会直接抛出带具体错误信息和示例格式的异常,方便你快速定位问题文件。

Do I need a changeset for every change?——不是每次改动都需要

不需要。 因为 changeset 描述的是"一个变更应该如何被发布",所以不需要触发发布的改动就不需要 changeset。例如:

  • 只修改了测试、文档或 CI 配置;
  • 修改了某个包的 devDependencies(不影响发布产物的行为);
  • 重构但对外行为不变,且你不希望触发版本升级。

判断标准很简单:如果你的改动不会导致任何包需要发新版本,就无需添加 changeset;反之,只要有一个包需要发布,就应为其生成对应的 changeset。如果想了解更完整的判断与使用思路,可以继续阅读入门指南和 docs 下的添加 changeset 详解。

How do I add a changeset?——三步交互式创建

最推荐的方式是运行 CLI 生成 changeset。根据你使用的包管理器,命令略有不同:

# pnpm
$ pnpm changeset
# npm
$ npx @changesets/cli
# yarn
$ yarn changeset

命令启动后会进入交互式向导,按提示依次完成三个步骤:

  1. 选择要包含的包(仅当项目包含多个包时出现)

    • 使用 ↑ / ↓ 在包列表中导航;
    • 按 space 勾选包(可多选);
    • 全部选好后按 enter 确认。
  2. 为每个选中的包选择适当的 semver 升级类型:major(破坏性变更)、minor(向后兼容的新功能)或 patch(向后兼容的缺陷修复)。

  3. 为 changeset 撰写一段摘要信息。这段文字将在下次版本发布时被写入 CHANGELOG。虽然并非每个 changeset 都需要长篇大论,但一份高质量的摘要至少应包含三要素:

    • WHAT:变更的内容是什么;
    • WHY:为什么要做这个变更;
    • HOW:使用方应该如何迁移或更新代码。

完成向导后,CLI 会在项目的 .changeset 目录下生成一个新的 Markdown 文件。确认内容无误后,把这个文件提交到你的分支即可。

从实现上看,add 命令会先通过 ensureChangesetFolder 确认 .changeset 目录存在(不存在会提示先运行 changeset init,见 packages/cli/src/commands/shared.ts),随后过滤出"可版本化"的包(排除配置中 ignore 的包和未开启版本管理的私有包),并尽量识别自基线分支以来发生过变更的包、在交互界面里帮你预选,降低选择成本。除交互模式外,add 命令还支持若干非交互参数:--empty(生成空 changeset)、--open(生成后直接用编辑器打开)、--message(直接指定摘要)、--since <ref>(基于指定 git ref 识别变更包),以及 --major / --minor / --patch(按包名直接指定升级类型)。当 changeset 包含 major 变更时,CLI 会额外给出强提醒,要求你补充破坏性变更的 WHAT / WHY / HOW。

Can I add more than one changeset in a PR?——可以,changeset 天然支持堆叠

可以,而且这是设计上就支持的用法。 changeset 设计为可堆叠(stack),在一个 PR 里添加多个 changeset 完全没有问题。典型场景包括:

  • 希望多个包分别发布、各自拥有独立的 CHANGELOG 条目;
  • 对同一个包做了多次彼此独立的改动,希望每条改动在 CHANGELOG 中分别被点名提及。

每个 changeset 文件相互独立、互不影响,changeset version 会读取 .changeset 目录下的全部 changeset 并汇总成一个发布计划(release plan)。这种"一改动一 changeset"的粒度,让变更历史更清晰、回滚和审计更容易。

Can I manually edit a changeset?——可以,文件名、摘要和 frontmatter 都能改

可以。 changeset 生成之后、发布之前,你可以随意手动编辑:

  • 文件名:默认使用随机的人类可读名称(由 write 包的 humanId 生成,如 tidy-pandas-whisper),目的是避免多人并发提交时产生 git 冲突。改名没有副作用,只要保持 .md 后缀并位于 .changeset 目录下即可。
  • Markdown 摘要:随时可以扩写或精简。
  • YAML frontmatter:包名和 bump 类型都可以修改,但必须保证是合法的包名、且版本类型属于 major / minor / patch / none,否则解析时会报错(见 packages/parse/src/index.ts 的校验逻辑)。

另外,只要 changeset 还没有被发布,你也可以直接删除它。如果你发现之前的某次改动不需要发布,删掉对应文件即可,不会产生任何副作用。

Are changesets removed?——版本命令会消费并删除 changeset

会。 当运行 changeset version 时,所有已消费的 changeset 文件都会被移除。这正是"一个 changeset 只用一次"设计原则的体现:它的信息(摘要 + bump 类型)在发布计划中被转化成了 CHANGELOG 条目和 package.json 里的新版本号,文件本身的历史使命就此完成。

具体到实现:changeset version 会先读取全部 changeset 与预发布状态,再调用 assembleReleasePlan 汇总发布计划,最后交给 applyReleasePlan 执行——更新各包版本号、生成 CHANGELOG 条目,并逐个删除已被消费的 changeset 文件(packages/apply-release-plan/src/index.ts)。需要注意两个例外:

  • 被跳过(skipped)的包对应的 changeset 不会被删除,因为包没有发布、信息还需保留;
  • 处于预发布(pre)模式时,changeset 不是被删除,而是被移动到 .changeset/pre/ 子目录暂存,待预发布结束(changeset pre exit)后再统一消费。

readChangesets 在读取时也只把 .changeset 目录下以 .md 结尾、不以 . 开头、且不属于 README.md / AGENTS.md / CLAUDE.md / GEMINI.md 等白名单文件的文件当作 changeset(packages/read/src/index.ts),目录下其余文件会被忽略。

正因为 changeset version 会定期清空 .changeset 目录,这里非常不适合存放任何其他重要信息——一旦运行版本命令,非 changeset 的普通文件虽然不会被删除,但目录内的内容会随发布节奏反复变动,容易造成混乱或误删。.changeset 目录就只应该做一件事:存放待发布的 changeset 文件(以及 config.json 等 changeset 自身配置)。

总结

至此,changeset 的完整生命周期已经清晰:交互式创建(或手动编写)→ 提交到分支 → 需要时编辑/删除 → changeset version 消费并清理。把握住"changeset = 待发布变更的临时载体"这一核心认知,就能正确地决定何时该加、加几个、怎么写、何时会被移除。如果想进一步了解 changeset 从"文件"到"发布计划"再到"版本号与 CHANGELOG"的完整转化过程,推荐继续阅读版本化与发布指南与技术决策记录。

登录后查看全文
changesets