Changesets 版本管理与发布指南:从 `changeset version` 到 `changeset publish` 的完整流程
Changesets 版本管理与发布指南:从 changeset version 到 changeset publish 的完整流程
版本管理与发布是 Changesets 工作流的最后两个关键环节:当仓库中积累了一批 changeset 之后,你需要通过 CLI 更新各包的版本号与 CHANGELOG,并将新版本发布到 npm。本指南以 Changesets 官方文档为主线,结合仓库源码(packages/cli/src/commands/version/index.ts、packages/cli/src/commands/publish/index.ts)讲解这两个命令的完整用法、底层原理、首次发布的权限配置(含 Trusted Publishing)以及移除包的正确姿势,帮助你建立一套可持续、可自动化的发布流程。
两步发布模型:为什么 version 与 publish 要分离
Changesets 将发布过程明确拆分为两个独立步骤:
- Versioning(版本化):根据已积累的 changeset,更新各包的
package.json版本号、内部依赖版本范围,并生成/追加 CHANGELOG 条目。 - Publishing(发布):把新版本上传到 npm,并为每个包创建 git tag。
两者的分离并非偶然:version 负责发布前所有文件层面的变更,publish 则只做“上传 + 打标签”的动作。中间留出的空隙允许你在合并发布之前审查版本号与 CHANGELOG 是否符合预期,确认无误后再真正发布。这一点在 CLI 参考文档 中有明确强调:
因为
publish命令假设最后一次 commit 就是版本提交(version commit),所以不要在version与publish之间提交任何其他变更。两个命令分离正是为了让你能先检查发布变更是否准确。
从源码看,这种“只管文件、不管网络”的分工也非常清晰:version 命令(packages/cli/src/commands/version/index.ts)的核心调用链是 readChangesets → assembleReleasePlan → applyReleasePlan,全程只操作本地文件;而 publish 命令(packages/cli/src/commands/publish/index.ts)则聚焦于 npm publish 与 git tag 的创建。
Versioning:运行 changeset version 更新版本与 CHANGELOG
在任一包管理器下运行 version 命令:
::: code-group
$ pnpm changeset version
$ npx @changesets/cli version
$ yarn changeset version
:::
命令完成后,需要审查改动,确认版本号和 CHANGELOG 符合预期,然后提交到仓库:
$ git add .
$ git commit -m "Version packages"
如果配置了 commit 选项(true 或自定义提交信息生成器),changeset version 会自动完成上述 git add 与 commit 操作。从源码看,该逻辑位于 version 命令的末尾:它通过 getCommitFunctions 获取提交信息生成函数,将 applyReleasePlan 返回的所有被改动文件逐个 git add 后执行一次提交(packages/cli/src/commands/version/index.ts)。
version 命令内部到底做了什么
以源码为依据,changeset version 的执行流程如下(packages/cli/src/commands/version/index.ts):
- 读取工作区所有包(
getPackages)与配置(readConfig),必要时执行--ignore/ 配置ignore的冲突校验; - 并行读取所有待发布 changeset(
readChangesets)与 pre 模式状态(readPreState); - 若处于 prerelease 模式(
pre mode)而你想做正常发布,命令会给出警告并要求先执行changeset pre exit; - 若没有任何未发布的 changeset,命令以错误退出(
No unreleased changesets found.),避免空跑; - 通过
assembleReleasePlan生成发布计划,再交给applyReleasePlan实际改写各包的版本号、依赖范围与 CHANGELOG。
其中依赖版本范围的更新逻辑位于 packages/apply-release-plan/src/version-package.ts:它会遍历 dependencies、devDependencies、peerDependencies、optionalDependencies 四类依赖,依据 updateInternalDependencies(默认 "patch")等配置决定是否将内部依赖范围升级到新版本;workspace: 协议与 file:/link: 协议的范围也会被正确处理。CHANGELOG 条目则按 major/minor/patch 分组生成(packages/apply-release-plan/src/get-changelog-entry.ts),并通过 changelog 配置的生成器格式化。
进阶用法:--ignore 与 --snapshot
--ignore <pkg>:跳过指定包,实现仓库的部分发布。注意它复用了配置ignore的安全约束:若被忽略的包出现在一个同时包含未忽略包的 changeset 中,或某个未被忽略的包依赖了被忽略包,version 会直接失败(详见 CLI 参考)。--snapshot:生成仅用于测试的 快照版本,可用--snapshot-prerelease-template <template>定制后缀,等价于配置项snapshot.prereleaseTemplate。另外从源码可以看到,snapshot 模式下会自动禁用commit行为,避免把快照版本改动提交进 git(packages/cli/src/commands/version/index.ts)。
Publishing:运行 changeset publish 发布到 npm 并创建 git tag
版本提交完成后,运行 publish 命令:
::: code-group
$ pnpm changeset publish
$ npx @changesets/cli publish
$ yarn changeset publish
:::
publish 命令的工作原理:逐个进入每个包,检查其 package.json 中的版本是否已经发布到 npm,若尚未发布则执行 npm publish(或根据检测到的包管理器使用对应的发布命令,如 pnpm/yarn)。代码中会先通过 getPublishPlan 生成发布计划,计划为空时输出 No unpublished projects to publish. 并直接返回(packages/cli/src/commands/publish/index.ts)。
发布采用按依赖图分块(chunk)的队列策略:先发布被依赖的包,再发布依赖方;在本地 TTY 环境中遇到需要 2FA 的包会进入交互式重试流程,并提供 --otp 参数在非交互环境直接传入一次性密码(packages/cli/src/commands/publish/index.ts)。
git tag 的命名规则与推送
publish 命令默认会为每个已成功发布的包创建 git tag,方便用户定位某个具体版本的代码:
- 多包仓库(monorepo):tag 格式为
pkg-name@X.X.X,例如my-package@1.2.0; - 单包仓库:tag 格式为
vX.X.X,例如v1.2.0。
该规则由 packages/cli/src/utils/gitTags.ts 的 buildGitTag 实现:tool.type !== "root"(即非单包 root 仓库)时使用 name@version,否则使用 vversion。创建 tag 前还会检查本地与远端是否已存在同名 tag,已存在的会被跳过并归入 "Skipped tags (already exist)"(packages/cli/src/commands/git-tag/utils.ts)。
创建完 tag 后,记得推送:
$ git push --follow-tags
如果你不需要 git tag(例如有独立的发布流程),可以传入 --no-git-tag 禁用。
其他常用发布选项
--otp <code>:本地发布且 npm 开启了双因素认证时,直接传入 OTP 避免交互式提示(CLI 参考)。--tag <name>:为本次发布指定 npm dist-tag。默认使用latest;发布快照版本时建议使用独立 tag(如beta),避免被用户默认安装(CLI 参考)。注意源码中校验了自定义 tag 与 pre 模式、artifact 模式(--from-pack-dir)的兼容性(packages/cli/src/commands/publish/index.ts)。--from-pack-dir <dir>:配合pack命令将本地构建的 tarball 发布出去,适合把构建与发布拆开的 CI 流水线。
警惕意外发布新包
由于 publish 命令会自动发布所有“尚未发布过”的版本,它有可能意外发布一个从未被 version 处理过的新包(例如在自动化流程、快照发布场景下)。防止办法:在 package.json 中为不应发布的包设置 "private": true(详见 CLI 参考 中的警告)。
完整的发布循环
一次发布完成之后,整个流程并没有结束。当你再次添加新的 changeset,重复上述两个步骤即可持续发布新版本:
- 开发时通过
changeset add记录变更; - 合并代码后运行
changeset version更新版本与 CHANGELOG,审查并提交; - 运行
changeset publish发布到 npm 并创建 git tag; git push --follow-tags推送 tag。
如果觉得手动执行太繁琐,可以参考 CI 自动化指南——它展示了如何让发布变得像合并一个 PR 一样简单(例如用 changeset status --since main 在 CI 中做阻塞式 changeset 检查、用 Changesets GitHub Action 自动创建版本 PR 并发布)。如果需要在旧版本上发布修复,请参阅 Backporting Changes。
发布到非包根目录
Changesets 支持在 package.json 中通过 publishConfig.directory 指定发布目录(而非包根目录)。该行为与 pnpm 的支持方式一致,但 Changesets 对其做了归一化处理,使其在所有包管理器下都能正常工作。
Publishing for the First Time:首次发布前的权限配置
对于首次发布的包,必须正确设置 access 选项。该配置类型为 "restricted" | "public",默认值为 "restricted"——因为 npm 默认将 scoped 包发布为 restricted(私有),Changesets 默认跟随该行为以防意外公开代码,所以大多数项目需要显式改为 public。
如果你的所有包都是公开的,在 .changeset/config.json 中设置:
{
"access": "public"
}
如果只有部分包是公开的,则在对应包的 package.json 中使用 publishConfig.access 字段:
{
"name": "@scope/pkg-a",
"version": "1.0.0",
"publishConfig": {
"access": "public"
}
}
对于私有包,请确保你拥有发布它们的权限;在 CI 中,需要把 npm access token 传给工作流。务必保护好 access token:
::: warning 保护你的 access token 始终对 access token 格外小心,不要在你的 CI 工作流中泄露它们。只把它们传给真正需要的步骤。否则,建议改用 Trusted Publishing。 :::
从源码角度看,access 配置最终会被读入发布计划:publish 命令通过 readConfig 读取 .changeset/config.json(packages/cli/src/utils/read-config.ts),并把每个包视为一个发布条目逐包处理。private 的包不会进入 npm 发布队列,这与你配置的 access 无关,是 publish 命令对私有包的基本处理。
Trusted Publishing:更安全的 CI 发布方式
如果你希望为一个新包启用 Trusted Publishing,需要先在本地手动发布一次该包,然后在其发布设置中开启 trusted publishing。通常的做法是:
- 先创建一个 stub 包,其
package.json如下:
{
"name": "pkg-a",
"version": "0.0.0"
}
- 运行
npm publish发布这个 stub(版本0.0.0),并在包的发布设置中配置 trusted publishing; - 然后创建一个 changeset,把版本提升到合适的初始版本。例如要从
0.1.0开始:
---
"pkg-a": minor
---
Initial release
之后走正常的 version + publish 流程即可。trusted publishing 让 CI 无需持有长效 token 即可发布,是目前 npm 推荐的安全方案;关于它在 GitHub Actions 中的完整配置(包括仅在发布 job 上设置 id-token: write、拆分构建/测试/发布 job、使用受保护 environment 等),请参考 CI 自动化指南。
Removing a Package:移除一个包
当某个包不再需要时,处理方式如下:
- 像平常一样删除该包的目录;
- 确保从现有 changeset 中移除所有对该包名的引用——搜索 changeset frontmatter 中诸如
"my-deleted-package": patch这样的行并删除。
完成这两步后,Changesets 会在下一次 version 和 publish 时自动跳过该包。反之,如果残留引用,assembleReleasePlan 在读取 changeset 时仍可能尝试为它生成发布计划,导致流程出错或产生无意义的发布条目。
结语
changeset version 与 changeset publish 构成了 Changesets 发布流程的一体两面:前者离线完成版本号、依赖范围与 CHANGELOG 的全部文件变更,后者负责将新版本送上 npm 并打好 git tag。配合 access/publishConfig.access 的权限配置、Trusted Publishing 的安全实践以及“删除包目录 + 清理 changeset 引用”的移除流程,你就能在单包仓库和 monorepo 中稳定地持续发布。更进一步的自动化(GitHub Bot 检查 changeset、Action 自动版本化与发布)请参见 Automating Changesets,完整的命令与配置参考见 CLI 参考 与 配置文件参考。