changesets

Changesets

概述

Changesets 是一款面向多包仓库的版本管理和变更日志管理工具。贡献者通过 changeset 文件声明每项变更对 semver 的影响（major/minor/patch），然后 Changesets 汇总这些文件，以统一协调的发布流程更新版本、变更日志并发布包。

适用场景： Monorepo 版本管理、自动生成变更日志、协调发布多个包、由 CI 驱动的发布、预发布/快照工作流。

不适用场景： 不发布 npm 包的单文件项目、使用基于提交消息的版本管理（semantic-release）的项目、不借助 npm registry 手动管理版本的项目，以及所有发布都由单个维护者控制、没有 PR 协作的项目。

工作原理

1. 贡献者添加一个 changeset 文件，声明受影响的包、版本升级类型和摘要
2. 在 PR 中将 changeset 文件与代码变更一同提交
3. 准备好发布时，changeset version 会处理所有待处理的 changeset，并更新版本和变更日志
4. changeset publish 会将更新后的包发布到 npm 并创建 git 标签
5. 在 CI 中，官方 GitHub Action 通过自动维护的“Version Packages”PR 自动执行第 3-4 步

核心概念

• Changeset 文件 — .changeset/ 中的 Markdown 文件，用于声明受影响的包、版本升级类型（major/minor/patch），以及会显示在变更日志中的易读摘要
• 版本命令 — 处理所有待处理的 changeset 文件，计算最终的版本升级，更新 package.json 中的版本，生成 CHANGELOG.md 条目，并升级内部依赖范围
• 发布命令 — 将更新后的包发布到 npm 并创建 git 标签；必须在 version 之后立即运行，中间不能有提交
• 关联包 — 在一次发布中共享最高版本升级类型、但保留独立版本号的包
• 固定版本包 — 组内始终使用完全相同版本号的包
• 预发布模式 — 在此模式下，version 会生成预发布版本（例如 1.0.0-beta.0），用于在稳定版发布前进行测试
• 快照发布 — 用于临时测试的 0.0.0-timestamp 版本，不会影响主发布序列

配置快速参考

选项	默认值	描述
changelog	"@changesets/cli/changelog"	变更日志生成器包；设为 false 可禁用
commit	false	在 version 和 add 命令中自动提交
access	"restricted"	npm 发布访问权限；将公开作用域的包设为 "public"
baseBranch	"main"	用于检测变更的分支
linked	[]	共享最高版本升级类型的包组
fixed	[]	共享完全相同版本的包组
ignore	[]	从 changeset 版本管理中排除的包
updateInternalDependencies	"patch"	何时升级依赖项："patch" 或 "minor"
privatePackages	{ version: true, tag: false }	"private": true 的包的版本/标签行为

快速参考

模式	命令 / 配置	要点
初始化	npx @changesets/cli init	创建包含配置的 .changeset/ 文件夹
添加变更集	npx @changesets/cli add	交互式提示，选择软件包和版本升级类型
添加空变更集	npx @changesets/cli add --empty	声明无需为任何软件包设置版本（满足 CI 要求）
为软件包设置版本	npx @changesets/cli version	使用变更集、升级版本并更新变更日志
发布软件包	npx @changesets/cli publish	发布到 npm，并创建 git 标签
检查状态	npx @changesets/cli status	列出待处理的变更集；如果有变更缺少变更集，则以状态码 1 退出
检查分支以来的状态	npx @changesets/cli status --since=main	仅检查与 main 分支分歧以来的变更
进入预发布模式	npx @changesets/cli pre enter <tag>	启用预发布模式（beta、alpha、rc、next）
退出预发布模式	npx @changesets/cli pre exit	返回正常的版本管理模式
快照版本	npx @changesets/cli version --snapshot	创建 0.0.0-时间戳格式的版本以供测试
发布快照	npx @changesets/cli publish --tag canary --no-git-tag	发布快照，不覆盖 latest dist-tag
链接软件包	"linked": [["pkg-a", "pkg-b"]] in config	软件包共享最高的版本升级类型
固定软件包	"fixed": [["pkg-*"]] in config	软件包共享完全相同的版本号
忽略软件包	"ignore": ["pkg-internal"] in config	将软件包排除在变更集版本管理之外
公开访问	"access": "public" in config	发布公开作用域软件包的必需设置
GitHub 变更日志	"changelog": ["@changesets/changelog-github", ...]	添加 PR 链接和贡献者署名
自动提交	"commit": true in config	版本和添加命令会自动提交变更
内部依赖	"updateInternalDependencies": "patch" in config	控制何时升级内部依赖方的版本

常见错误

错误	正确做法
在 version 和 publish 之间提交	执行 version 后立即运行 publish，中间不要提交
忘记为没有软件包变更的 PR 使用 --empty	使用 npx @changesets/cli add --empty 通过 CI 检查
软件包必须使用完全相同的版本时使用 linked	版本相同时使用 fixed；linked 仅共享版本升级幅度
为公开软件包设置 access: "restricted"	在配置中为公开 npm 软件包设置 access: "public"
未在 CI 检出步骤中包含 fetch-depth: 0	检测 changeset 需要完整的 git 历史记录
未先构建就运行 publish	始终先运行构建步骤，再运行 changeset publish
在 main 分支进入预发布模式	使用专用分支进行预发布，避免阻塞正常发布
忽略其他软件包依赖的软件包	被忽略的软件包不会升级版本，导致依赖它们的软件包出问题——谨慎使用
使用默认标签发布快照	始终使用 --tag 标志，避免覆盖 latest dist-tag
未在 CI 环境中设置 NPM_TOKEN	自动发布需要同时设置 GITHUB_TOKEN 和 NPM_TOKEN
在 CI 中不使用 action 而运行 changeset publish	官方的 changesets/action 能正确处理双模式工作流
手动编辑生成的 CHANGELOG.md	改为编辑 changeset 文件；版本变更时会重新生成变更日志

委派

• CI 流水线调试：使用 Explore Agent 探索特定仓库的工作流
• npm 发布问题：使用 Task Agent 调试发布和注册表身份验证失败问题

如果有 turborepo 技能，请将构建编排、任务缓存和 CI 优化委派给它。 如果有 pnpm-workspace 技能，请将工作区设置、依赖关联、目录和 Docker 部署委派给它。请参阅其 monorepo 集成参考，了解端到端发布流水线。

参考资料

• 基本工作流：添加 changeset、版本管理、发布、CI 集成
• Monorepo 设置：配置、关联软件包、固定版本管理、忽略模式
• CI 自动化：GitHub Actions、自动化 PR、快照发布、预发布渠道