跳到主要内容

Changesets 是什么？一篇讲明白 Monorepo 里的版本管理和发版流程

6 分钟阅读

当项目开始走向 Monorepo，一个仓库里同时维护多个包时，很快就会遇到一个现实问题：

代码能一起写了，那版本号、CHANGELOG、发版流程怎么一起管？

这时候很多团队会用到一个工具：Changesets。

如果用一句最通俗的话解释它，可以这么理解：

Changesets 就像 Monorepo 里的“发版记录单”系统。

你每做完一次改动，就先记一张“这次改了什么、该升哪个版本”的单子；等准备发版时，再统一计算版本号、生成 CHANGELOG、执行发布。

它最适合的场景，就是：

  • 一个仓库里有多个 npm 包
  • 包和包之间有依赖关系
  • 团队希望版本管理更清晰、发布流程更自动化

一、先说结论：Changesets 到底解决了什么问题？​

如果项目里只有一个包，手动改版本号还不算特别痛苦。

但一旦到了 Monorepo，情况会立刻复杂很多。

比如你的仓库里有这些包：

packages/
├── cli-devkit
├── cli-plugin-publish
└── cli-plugin-changeset

而且：

  • cli-plugin-publish 依赖 cli-devkit
  • cli-plugin-changeset 也依赖 cli-devkit

这时候你会遇到几个典型问题：

  • 哪个包这次需要发版？
  • 它应该升 patch、minor 还是 major？
  • 如果底层包升级了，依赖它的其他包要不要一起变？
  • CHANGELOG 谁来写？
  • 多个人同时改包时，怎么避免版本管理混乱？

Changesets 就是专门解决这些问题的。

它最核心的能力有四个：

  • 管理多个包的版本号
  • 自动生成 CHANGELOG
  • 协调内部依赖包的版本更新
  • 协助完成发版流程

二、为什么 Monorepo 特别需要 Changesets？​

可以先想象一下，如果没有 Changesets，会发生什么。

1. 手动管理版本号很容易乱​

你改了一个包，要自己判断：

  • 这是 patch 还是 minor？
  • 版本该从 1.1.19 改到多少？
  • 改的是底层包，依赖它的上层包要不要一起动？

如果包只有一个，也许还能靠人脑记住。
但当仓库里有 5 个、10 个、20 个包时，这件事就很容易失控。

2. CHANGELOG 很容易没人维护​

理论上每次发版都应该有变更记录。
但现实是，很多团队最后都会变成：

  • 有人忘了写
  • 有人随便写一句
  • 有人直接不写

结果就是，版本发了，但过了几周大家都不记得这版到底改了什么。

3. 包之间有依赖关系，版本不是独立变化的​

例如：

  • cli-devkit 升级了
  • cli-plugin-publish 依赖它
  • cli-plugin-changeset 也依赖它

那你就不能只盯着一个包看，而要考虑整条依赖链。

这也是 Monorepo 发版麻烦的地方：

问题不是“改哪个包版本”，而是“哪些包会被这次改动影响”。

三、Changesets 的核心思路其实很简单​

很多人第一次接触 Changesets，会觉得它像一个复杂的发版工具。
其实它的思路非常朴素：

先记录变更，再统一处理版本。

也就是说，它不是要求你每改一次代码就立刻发版，而是分成两步：

  1. 平时开发时，先记录“这次改动将来要怎么发”
  2. 真正发版时，再统一计算版本、生成 CHANGELOG、执行发布

这也是它为什么特别适合团队协作。

因为每个开发者只需要对自己的改动负责，先写好“这次改了什么”；
至于最后怎么批量升级版本，交给 Changesets 统一处理。

四、Changesets 是怎么工作的？​

可以把它理解成 3 个阶段：

  1. 记录变更
  2. 计算版本
  3. 执行发布

下面逐个看。

1. 第一步：记录变更​

每次你完成一项功能或修复一个问题后，可以创建一个 changeset 文件：

npx @osl/cli changeset add

执行之后，它通常会生成一个文件，比如：

.changeset/cool-cats.md

内容可能长这样：

---
"@osl/tiny-plugin-publish": patch
---

修复了飞书文档标题包含分支名的问题

这个文件其实就是一张“发版记录单”，记录了三件事：

  • 哪个包要更新：@osl/tiny-plugin-publish
  • 更新类型：patch
  • 这次改动的描述：修复了什么问题

所以 changeset 文件本质上不是代码，而是：

一次改动对应的一份发布说明。

2. 第二步：统一计算版本​

等到准备发版时，再执行：

npx @osl/cli changeset version

这一步会做很多自动化工作：

  • 读取所有未消费的 changeset 文件
  • 计算每个包的新版本号
  • 更新各个包的 package.json
  • 生成或更新 CHANGELOG.md
  • 根据配置同步处理内部依赖版本
  • 删除已经处理过的 changeset 文件

版本号的计算遵循语义化版本（SemVer）：

  • patch：小修复，向后兼容，例如 1.1.19 -> 1.1.20
  • minor：新功能，向后兼容，例如 1.1.19 -> 1.2.0
  • major：破坏性更新，不向后兼容，例如 1.1.19 -> 2.0.0

也就是说，version 这一步不是“发包”，而是：

把之前记录好的变更，统一变成真正的版本号和 CHANGELOG。

3. 第三步：执行发布​

等版本和 changelog 都整理好之后，再进入发布阶段。

例如：

pnpm publish:local
# 或
pnpm publish:prod

具体命令会根据你的项目脚本不同而不同，但通常这一阶段会完成：

  • 构建包
  • 发布到 npm registry
  • 创建 git tag
  • 推送代码或发布结果

所以如果要一句话概括整个流程，就是：

changeset add 负责记账，changeset version 负责结算，publish 负责真正发出去。

五、把它放进真实工作流里，就很好理解了​

假设你修复了一个 bug，比如：

packages/cli-plugin-publish/src/lib/utils.ts

那么一套典型流程会是这样：

# 1. 修改代码

# 2. 创建 changeset，记录这次改动
npx @osl/cli changeset add

# 3. 提交代码和 changeset 文件
git add .
git commit -m "fix: 修复飞书文档标题"
git push

这时候通常还没有真正发版，只是把“将来要怎么发”记录下来了。

等真正准备发布时，再执行：

# 4. 统一计算版本和 changelog
npx @osl/cli changeset version

# 5. 提交版本更新结果
git add .
git commit -m "chore: version bump"
git push

# 6. 正式发布
pnpm publish:local

这个流程的好处是：

  • 平时开发时不用一边写代码一边手动改版本
  • 多个改动可以先积累，等到合适时机统一发版
  • 发版时不需要靠人肉统计“这次到底改了哪些包”

六、Changesets 为什么特别适合团队协作？​

因为它把“写代码”和“决定怎么发版”拆开了。

在团队协作里，每个开发者可以这样做：

  • 改自己的代码
  • 给自己的改动补一个 changeset
  • 把代码和 changeset 一起提交

这样等分支合并后，仓库里就自然积累了一批“待发布记录”。

等到发版时，Changesets 会把这些记录统一汇总起来。

这就比传统的人肉流程稳定很多：

  • 不容易漏掉变更
  • 不容易忘记写 CHANGELOG
  • 不需要靠某个人临时整理版本影响范围

所以你完全可以把 Changesets 理解成：

团队协作下的发版中间层。

七、内部依赖版本是怎么联动的？​

这是 Changesets 很有价值的一点。

比如你的配置里有这样一项：

{
  "updateInternalDependencies": "patch"
}

它的意思是：

如果某个内部依赖包升级了，那么依赖它的其他包也会按规则自动更新版本。

例如：

  • cli-devkit 从 1.0.0 升到 1.1.0
  • cli-plugin-publish 依赖 cli-devkit

那么在配置允许的情况下，cli-plugin-publish 也可能自动补一次版本更新，比如：

  • 1.1.19 -> 1.1.20

为什么要这样做？

因为在 Monorepo 里，发版不是孤立事件。
底层包一变，依赖它的上层包往往也受影响。

Changesets 能做的，就是把这种“依赖链上的版本联动”也纳入自动化流程里。

这样会带来几个好处：

  • 保持依赖关系一致
  • 减少版本冲突
  • 避免漏改依赖链上的包

八、版本类型到底怎么选？​

很多人刚用 Changesets 时，最容易纠结的就是：
这次到底该选 patch、minor 还是 major？

你可以先用最简单的方式记：

  • patch：修 bug，小修小补，不影响原有用法
  • minor：加新功能，但旧用法还能继续用
  • major：有破坏性变更，旧代码可能会失效

也可以直接对应成版本变化：

  • patch：1.1.19 -> 1.1.20
  • minor：1.1.19 -> 1.2.0
  • major：1.1.19 -> 2.0.0

如果你不确定怎么选，可以问自己一个问题：

“别人升级到我这个版本后，原来的代码会不会出问题？”

如果不会，多半是 patch 或 minor；
如果会，那大概率就是 major。

九、Changesets 的几个核心好处​

1. 版本管理自动化​

不用手动计算每个包该升到多少版本，工具会根据 changeset 统一处理。

2. CHANGELOG 更清晰​

变更记录不是临时回忆出来的，而是每次改动时就顺手记下来的。

3. 发布时机更灵活​

你可以积累多个 changeset，等到合适的时候一起发版，而不是每改一次就立刻发。

4. 团队协作更顺​

每个人都只需要为自己的改动补一张“记录单”，发版时统一汇总，流程更清晰。

5. 更适合 Monorepo​

因为它天然能处理多包版本、内部依赖和 changelog 这些 Monorepo 里的常见问题。

十、最后怎么记住 Changesets？​

如果要把它压缩成一句最容易记住的话，那就是：

Changesets = Monorepo 里的版本管理待办清单。

你可以把整个流程理解成：

  • 写代码：完成实际改动
  • 创建 changeset：记录“这次改动将来要怎么发”
  • 执行 version：统一计算版本号并生成 CHANGELOG
  • 执行 publish：真正把包发出去

所以它最重要的价值，并不是“帮你多跑了几个命令”，而是让发版这件事从“人肉记忆 + 手工操作”，变成“有记录、有规则、可自动化”的流程。

对于 Monorepo 来说，这一点非常重要。

Loading Comments...
0%