Changesets 版本管理与发布指南:从 `changeset version` 到 `changeset publish` 的完整流程

原创2026-09-22 19:43:061,874 阅读
文章标签:开发工具CLI

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 将发布过程明确拆分为两个独立步骤:

  1. Versioning(版本化):根据已积累的 changeset,更新各包的 package.json 版本号、内部依赖版本范围,并生成/追加 CHANGELOG 条目。
  2. 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):

  1. 读取工作区所有包(getPackages)与配置(readConfig),必要时执行 --ignore / 配置 ignore 的冲突校验;
  2. 并行读取所有待发布 changeset(readChangesets)与 pre 模式状态(readPreState);
  3. 若处于 prerelease 模式(pre mode)而你想做正常发布,命令会给出警告并要求先执行 changeset pre exit;
  4. 若没有任何未发布的 changeset,命令以错误退出(No unreleased changesets found.),避免空跑;
  5. 通过 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,重复上述两个步骤即可持续发布新版本:

  1. 开发时通过 changeset add 记录变更;
  2. 合并代码后运行 changeset version 更新版本与 CHANGELOG,审查并提交;
  3. 运行 changeset publish 发布到 npm 并创建 git tag;
  4. 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。通常的做法是:

  1. 先创建一个 stub 包,其 package.json 如下:
{
  "name": "pkg-a",
  "version": "0.0.0"
}
  1. 运行 npm publish 发布这个 stub(版本 0.0.0),并在包的发布设置中配置 trusted publishing;
  2. 然后创建一个 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:移除一个包

当某个包不再需要时,处理方式如下:

  1. 像平常一样删除该包的目录;
  2. 确保从现有 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 参考 与 配置文件参考。

登录后查看全文
changesets