Back to Details

changesets

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Changesets

Changesets

Overview

概述

Changesets is a versioning and changelog management tool focused on multi-package repositories. Contributors declare the semver impact of each change (major/minor/patch) via changeset files, then Changesets aggregates them to bump versions, update changelogs, and publish packages in a single coordinated release.
When to use: Monorepo versioning, automated changelog generation, coordinated multi-package releases, CI-driven publishing, prerelease/snapshot workflows.
When NOT to use: Single-file projects with no npm publishing, projects using commit-message-based versioning (semantic-release), manual version management without an npm registry, projects where a single maintainer controls all releases without PR collaboration.
Changesets是一款专注于多包仓库的版本管理与变更日志管理工具。贡献者通过changeset文件声明每个变更的semver影响（主版本/次版本/修订版本），随后Changesets会汇总这些信息，统一完成版本号升级、变更日志更新以及包发布工作。
适用场景： Monorepo版本管理、自动化变更日志生成、多包协同发布、CI驱动的包发布、预发布/快照版本流程。
不适用场景： 无需发布到npm的单文件项目、基于提交信息进行版本管理的项目（如semantic-release）、不依赖npm注册表的手动版本管理项目、由单一维护者全权控制发布且无需PR协作的项目。

How It Works

工作原理

  1. A contributor adds a changeset file declaring affected packages, bump types, and a summary
  2. The changeset file is committed alongside the code change in the PR
  3. When ready to release, 
    changeset version
    consumes all pending changesets and updates versions and changelogs
  4. changeset publish
    publishes the updated packages to npm and creates git tags
  5. In CI, the official GitHub Action automates steps 3-4 via an auto-maintained "Version Packages" PR
  1. 贡献者添加一个changeset文件，声明受影响的包、版本升级类型以及变更摘要
  2. 该changeset文件与代码变更一起提交到PR中
  3. 准备发布时，执行
    changeset version
    命令，处理所有待处理的changeset，更新版本号和变更日志
  4. 执行
    changeset publish
    命令，将更新后的包发布到npm并创建git标签
  5. 在CI环境中，官方GitHub Action会通过自动维护的“Version Packages”PR自动完成步骤3-4

Key Concepts

核心概念

  • Changeset file — A markdown file in 
    .changeset/
    declaring which packages are affected, their bump type (major/minor/patch), and a human-readable summary that appears in the changelog
  • Version command — Consumes all pending changeset files, calculates final version bumps, updates 
    package.json
    versions, generates 
    CHANGELOG.md
    entries, and bumps internal dependency ranges
  • Publish command — Publishes updated packages to npm and creates git tags; must run immediately after 
    version
    with no commits in between
  • Linked packages — Packages that share the highest bump type within a release but maintain independent version numbers
  • Fixed packages — Packages that always share the exact same version number across the group
  • Prerelease mode — A mode where 
    version
    produces prerelease versions (e.g., 
    1.0.0-beta.0
    ) for testing before stable release
  • Snapshot releases — Temporary 
    0.0.0-timestamp
    versions for ad-hoc testing without affecting the main release line
  • Changeset文件 — 位于
    .changeset/
    目录下的Markdown文件，声明受影响的包、版本升级类型（主版本/次版本/修订版本），以及会显示在变更日志中的人类可读摘要
  • Version命令 — 处理所有待处理的changeset文件，计算最终版本升级幅度，更新
    package.json
    中的版本号，生成
    CHANGELOG.md
    条目，并升级内部依赖的版本范围
  • Publish命令 — 将更新后的包发布到npm并创建git标签；必须在
    version
    命令执行后立即运行，中间不能有其他提交
  • 关联包（Linked packages） — 在一次发布中共享最高版本升级类型，但保持独立版本号的包组
  • 固定版本包（Fixed packages） — 始终共享完全相同版本号的包组
  • 预发布模式 — 一种特殊模式，执行
    version
    命令会生成预发布版本（如
    1.0.0-beta.0
    ），用于稳定版发布前的测试
  • 快照版本 — 临时的
    0.0.0-timestamp
    版本，用于临时测试，不会影响正式发布线

Configuration Quick Reference

配置速查

OptionDefaultDescription
changelog
"@changesets/cli/changelog"
Changelog generator package or 
false
to disable
commit
false
Auto-commit on 
version
and 
add
commands
access
"restricted"
npm publish access; set 
"public"
for public scoped packages
baseBranch
"main"
Branch used for change detection
linked
[]
Groups of packages that share highest bump type
fixed
[]
Groups of packages that share exact version
ignore
[]
Packages excluded from changeset versioning
updateInternalDependencies
"patch"
When to bump dependents: 
"patch"
or 
"minor"
privatePackages
{ version: true, tag: false }
Version/tag behavior for 
"private": true
packages
选项默认值说明
changelog
"@changesets/cli/changelog"
变更日志生成器包，设置为
false
可禁用变更日志生成
commit
false
在
version
和
add
命令执行后自动提交变更
access
"restricted"
npm发布权限；对于公开的作用域包，需设置为
"public"
baseBranch
"main"
用于检测变更的基准分支
linked
[]
共享最高版本升级类型的包组
fixed
[]
共享完全相同版本号的包组
ignore
[]
排除在Changesets版本管理之外的包
updateInternalDependencies
"patch"
何时升级内部依赖的版本：
"patch"
或
"minor"
privatePackages
{ version: true, tag: false }
标记为
"private": true
的包的版本/标签行为设置

Quick Reference

命令速查

PatternCommand / ConfigKey Points
Initialize
npx @changesets/cli init
Creates 
.changeset/
folder with config
Add changeset
npx @changesets/cli add
Interactive prompt for packages and bump type
Add empty changeset
npx @changesets/cli add --empty
Declares no packages need versioning (satisfies CI)
Version packages
npx @changesets/cli version
Consumes changesets, bumps versions, updates changelogs
Publish packages
npx @changesets/cli publish
Publishes to npm, creates git tags
Check status
npx @changesets/cli status
Lists pending changesets; exits 1 if changes lack changesets
Status since branch
npx @changesets/cli status --since=main
Only checks changes since diverging from main
Enter prerelease
npx @changesets/cli pre enter <tag>
Enables prerelease mode (beta, alpha, rc, next)
Exit prerelease
npx @changesets/cli pre exit
Returns to normal versioning mode
Snapshot version
npx @changesets/cli version --snapshot
Creates 0.0.0-timestamp versions for testing
Snapshot publish
npx @changesets/cli publish --tag canary --no-git-tag
Publishes snapshot without overwriting latest dist-tag
Link packages
"linked": [["pkg-a", "pkg-b"]]
in config		Packages share the highest version bump type
Fix packages
"fixed": [["pkg-*"]]
in config		Packages share the exact same version number
Ignore packages
"ignore": ["pkg-internal"]
in config		Excludes packages from changeset versioning
Public access
"access": "public"
in config		Required for publishing public scoped packages
GitHub changelog
"changelog": ["@changesets/changelog-github", ...]
Adds PR links and contributor attribution
Auto-commit
"commit": true
in config		Version and add commands auto-commit changes
Internal deps
"updateInternalDependencies": "patch"
in config		Controls when internal dependents get bumped
场景命令 / 配置关键要点
初始化
npx @changesets/cli init
创建包含配置文件的
.changeset/
目录
添加changeset
npx @changesets/cli add
交互式提示选择受影响的包和版本升级类型
添加空changeset
npx @changesets/cli add --empty
声明无包需要升级版本（用于满足CI检查）
升级包版本
npx @changesets/cli version
处理所有待处理的changeset，升级版本号并更新变更日志
发布包
npx @changesets/cli publish
发布到npm并创建git标签
检查状态
npx @changesets/cli status
列出所有待处理的changeset；如果变更未添加changeset则返回状态码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-timestamp
格式的版本用于测试
发布快照版本
npx @changesets/cli publish --tag canary --no-git-tag
发布快照版本，且不会覆盖
latest
标签
关联包
"linked": [["pkg-a", "pkg-b"]]
in config		包组共享最高版本升级幅度
固定包版本
"fixed": [["pkg-*"]]
in config		包组共享完全相同的版本号
忽略包
"ignore": ["pkg-internal"]
in config		将包排除在Changesets版本管理之外
公开访问权限
"access": "public"
in config		发布公开npm包时必须设置
GitHub风格变更日志
"changelog": ["@changesets/changelog-github", ...]
添加PR链接和贡献者信息
自动提交
"commit": true
in config		version和add命令执行后自动提交变更
内部依赖升级
"updateInternalDependencies": "patch"
in config		控制何时升级内部依赖的版本

Common Mistakes

常见错误

MistakeCorrect Pattern
Committing between 
version
and 
publish
Run 
publish
immediately after 
version
with no commits in between
Forgetting 
--empty
for PRs with no package changes		Use 
npx @changesets/cli add --empty
to satisfy CI checks
Using 
linked
when packages must share exact versions		Use 
fixed
for identical versions; 
linked
only shares bump magnitude
Setting 
access: "restricted"
for public packages		Set 
access: "public"
in config for public npm packages
Not including 
fetch-depth: 0
in CI checkout		Full git history is needed for changeset detection
Running 
publish
without building first		Always run build step before 
changeset publish
Entering prerelease mode on main branchUse a dedicated branch for prereleases to avoid blocking normal releases
Ignoring packages that others depend onIgnored packages skip bumps, breaking dependents — use sparingly
Publishing snapshots with default tagAlways use 
--tag
flag to avoid overwriting 
latest
dist-tag
Not setting 
NPM_TOKEN
in CI environment		Both 
GITHUB_TOKEN
and 
NPM_TOKEN
are required for automated publishing
Using 
changeset publish
in CI without the action		The official 
changesets/action
handles the two-mode workflow correctly
Manually editing generated 
CHANGELOG.md
Edit changeset files instead; changelogs are regenerated on 
version
错误操作正确做法
在
version
和
publish
命令之间提交变更		执行
version
后立即运行
publish
，中间不能有任何提交
无包变更的PR未添加空changeset使用
npx @changesets/cli add --empty
来满足CI检查
当包需要共享完全相同版本时使用
linked
配置		包版本完全相同时使用
fixed
配置；
linked
仅共享版本升级幅度
公开包设置
access: "restricted"
公开npm包需在配置中设置
access: "public"
CI检出时未设置
fetch-depth: 0
Changeset检测需要完整的git历史
未构建就执行
publish
命令		执行
changeset publish
前必须先完成构建步骤
在主分支进入预发布模式使用专门的分支进行预发布，避免阻塞正常版本发布
忽略被其他包依赖的包被忽略的包不会升级版本，会导致依赖它的包出现问题——需谨慎使用
使用默认标签发布快照版本发布快照版本时必须使用
--tag
参数，避免覆盖
latest
标签
CI环境中未设置
NPM_TOKEN
自动发布需要同时配置
GITHUB_TOKEN
和
NPM_TOKEN
CI中直接使用
changeset publish
而不使用官方Action		官方
changesets/action
能正确处理双模式工作流
手动编辑自动生成的
CHANGELOG.md
如需修改变更日志，请编辑changeset文件；
version
命令会重新生成变更日志

Delegation

任务委托

  • CI pipeline debugging: Use 
    Explore
    agent for repository-specific workflow discovery
  • npm publishing issues: Use 
    Task
    agent for debugging publish and registry authentication failures
If the 
turborepo
skill is available, delegate build orchestration, task caching, and CI optimization to it. If the 
pnpm-workspace
skill is available, delegate workspace setup, dependency linking, catalogs, and Docker deployment to it. See its monorepo integration reference for the end-to-end release pipeline.
  • CI流水线调试：使用Explore Agent进行仓库特定的工作流排查
  • npm发布问题：使用Task Agent调试发布和注册表认证失败问题
如果
turborepo
技能可用，将构建编排、任务缓存和CI优化工作委托给它。 如果
pnpm-workspace
技能可用，将工作区设置、依赖关联、目录管理和Docker部署工作委托给它。请参考其Monorepo集成文档获取端到端的发布流程说明。

References

参考资料

  • Basic workflow: adding changesets, versioning, publishing, CI integration
  • Monorepo setup: configuration, linked packages, fixed versioning, ignore patterns
  • CI automation: GitHub Actions, automated PRs, snapshot releases, prerelease channels
  • 基础工作流：添加changeset、版本升级、发布、CI集成
  • Monorepo配置：配置项、关联包、固定版本、忽略规则
  • CI自动化：GitHub Actions、自动PR、快照发布、预发布通道