Changesets

Monorepo 版本管理与变更日志生成工具，通过声明式 changeset 文件协调多包发布流程。

技术简介说明

Changesets 是一个专注于 monorepo（多包仓库）的版本管理和变更日志工具。它让贡献者在提交代码变更时声明该变更的发布方式，然后自动更新包版本、生成变更日志，并发布新版本。核心理念是将"发布意图"与"代码变更"解耦——每个 changeset 代表以特定 semver 升级类型（major/minor/patch）发布一组包的意图，并附带人类可读的变更摘要。

在 monorepo 场景下，Changesets 解决了多包协调发布的核心痛点：内部依赖关系自动同步更新、各包独立版本控制、跨包变更聚合、预发布版本管理等。它采用两阶段发布流程（Version PR + 发布），让每次发布都经过人工审核，降低了自动化发布带来的风险。

Changesets 最初由 Atlassian 团队为 Atlaskit 项目开发，后由 Thinkmill 赞助完成 v2 重构并开源。截至 2026 年，它已成为 monorepo 版本管理的事实标准，被 Astro、SvelteKit、Chakra UI、pnpm、Firebase JS SDK、Remix、XState 等 30+ 知名开源项目采用，npm 周下载量约 300 万。

基本信息

快速上手

安装

# 在 monorepo 根目录安装
npm install @changesets/cli
 
# 或使用 pnpm
pnpm add @changesets/cli
 
# 或使用 yarn
yarn add @changesets/cli

基础配置

运行初始化命令创建 .changeset 目录和配置文件：

npx changeset init

这会生成：

• .changeset/README.md - 说明文档
• .changeset/config.json - 核心配置文件

关键配置选项（.changeset/config.json）：

{
  "$schema": "https://unpkg.com/@changesets/[email protected]/schema.json",
  "changelog": "@changesets/cli/changelog",
  "commit": false,
  "fixed": [],
  "linked": [],
  "access": "public",
  "baseBranch": "main",
  "updateInternalDependencies": "patch",
  "ignore": [],
  "___experimentalUnsafeOptions_WillChangeInNext": {
    "onlyUpdatePeerDependentsWhenOutOfRange": true
  }
}

重要配置说明：

• access: "public" 发布到 npm 公共 registry，"restricted" 发布到私有 registry
• updateInternalDependencies: 内部依赖升级策略，"patch" 表示始终更新，"minor" 仅在 minor/major 时更新
• fixed: 固定版本包组（版本始终保持一致）
• linked: 关联版本包组（版本协调但可独立）
• ignore: 忽略版本管理的包（通常是应用而非库）

最小示例

1. 创建 changeset

npx changeset

交互式提示选择包、版本类型（major/minor/patch）、输入变更摘要。生成的 changeset 文件格式：

---
"my-package": minor
"another-package": patch
---
 
添加了新特性并修复了性能问题

2. 更新版本

npx changeset version

该命令会：

• 读取所有 changeset 文件
• 更新 package.json 中的版本号
• 更新 CHANGELOG.md
• 删除已处理的 changeset 文件

3. 发布包

npx changeset publish

该命令会：

• 发布所有更新过的包到 npm
• 生成 git tags
• 需要手动执行 git push --follow-tags

核心概念与架构

核心概念

Changeset（变更集）

• 代表"发布意图"的 Markdown 文件，包含 YAML front matter
• 存储在 .changeset/ 目录，文件名随机生成
• 包含：包列表、版本类型（major/minor/patch）、变更摘要

两阶段发布流程

1. 开发阶段：开发者在 PR 中添加 changeset 描述变更意图
2. 发布阶段：合并 Version PR 后自动更新版本、生成 changelog、发布包

版本协调机制

• Fixed packages：版本始终保持一致（如 @babel/core 和 @babel/cli）
• Linked packages：版本协调但可独立升级
• Independent packages：完全独立版本

内部依赖管理 当包 A 依赖包 B，且 B 发生版本升级时，Changesets 会自动更新 A 的 package.json 中 B 的版本号，确保依赖关系正确。

工作原理

1. 开发者创建 PR
   ↓
2. 运行 changeset 命令添加 changeset 文件
   ↓
3. PR 合并到主分支
   ↓
4. CI 运行 changeset version 命令
   ↓
5. 创建 Version PR（包含版本更新、changelog 更新）
   ↓
6. 合并 Version PR
   ↓
7. CI 运行 changeset publish 命令
   ↓
8. 包发布到 npm，生成 git tags

核心特性

• Monorepo 原生支持 专为多包仓库设计，自动处理内部依赖关系，支持各包独立版本

• 声明式发布意图 通过 changeset 文件明确表达发布意图，而非依赖提交信息格式

• 两阶段发布流程 Version PR 审核机制，每次发布都经过人工确认，降低自动化风险

• 自动 changelog 生成 根据 changeset 内容自动生成结构化的变更日志

• 预发布版本支持 支持 prerelease（如 alpha、beta、rc）和 snapshot releases

• 灵活的版本协调 支持 fixed（固定版本）和 linked（关联版本）两种协调模式

• CI/CD 集成 提供 GitHub Action 和 GitHub Bot，完整的自动化发布工作流

• 自定义 changelog 格式 支持自定义 changelog 生成器和格式化规则

• 快照发布 支持基于 commit 的快照版本，适合频繁发布的场景

• 版本应用支持 不仅支持 npm 包，也可管理应用程序版本（通过 @changesets/cli 的 version 命令）

生态图

核心包

官方扩展

@changesets/changelog-github

• 生成包含 GitHub PR 链接的 changelog
• 自动识别 PR 编号和作者
• 推荐在开源项目中使用

@changesets/action

• GitHub Action 自动化工作流
• 自动创建 Version PR
• 自动发布包到 npm
• 自动创建 GitHub Release

@changesets/bot

• GitHub Bot（Changeset Bot）
• 检查 PR 是否包含 changeset
• 在 PR 中添加评论提醒

社区生态

第三方 changelog 生成器

• @changesets/changelog-github - GitHub 风格
• 自定义生成器（实现 getChangelogEntry 函数）

集成工具

• turbo - Turborepo 任务编排
• nx - Nx 构建系统
• lerna - 传统 monorepo 工具

文档和教程

• Changesets 官方文档
• Vercel Academy - Changesets for Versioning
• Infinum Frontend Handbook

适用场景

• 开源 Monorepo 多包开源项目，需要协调发布和独立版本控制（如 UI 组件库、工具库集合）

• 企业内部 Monorepo 企业级 monorepo，需要严格的版本审核和发布流程

• 多包 NPM 发布 需要发布多个相互依赖的 npm 包，自动处理内部依赖更新

• 预发布管理 需要管理 alpha、beta、rc 等预发布版本

• 频繁快照发布 需要基于 commit 生成快照版本，支持持续集成和早期测试

• 跨团队协作 多团队共同维护 monorepo，需要明确的变更声明和审核机制

• 版本一致性要求高 需要保证相关包版本同步升级，避免版本不兼容问题

开发与工程化

开发流程

日常开发工作流

# 1. 创建功能分支
git checkout -b feature/new-feature
 
# 2. 开发功能并创建 changeset
npx changeset
# 选择影响的包、版本类型、输入变更摘要
 
# 3. 提交代码和 changeset 文件
git add .
git commit -m "feat: 添加新特性"
git push origin feature/new-feature
 
# 4. 创建 PR（PR 中应包含 changeset 文件）

发布工作流

# 1. 合并功能 PR 到主分支后，运行版本更新
npx changeset version
 
# 2. 提交版本更新
git add .
git commit -m "chore: 更新版本"
git push
 
# 3. 发布到 npm
npx changeset publish
 
# 4. 推送 git tags
git push --follow-tags

CI/CD 集成

GitHub Actions 完整示例

name: Release
 
on:
  push:
    branches:
      - main
 
concurrency: ${{ github.workflow }}-${{ github.ref }}
 
jobs:
  release:
    name: Release
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
 
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20
 
      - name: Install dependencies
        run: npm ci
 
      - name: Build
        run: npm run build
 
      - name: Create Release Pull Request or Publish
        id: changesets
        uses: changesets/action@v1
        with:
          publish: npm run release
          version: npm run version
          commit: "chore: 更新版本"
          title: "chore: 发布新版本"
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

配置说明：

• publish: 发布命令，通常是 npm run release 或直接 npx changeset publish
• version: 版本更新命令，通常是 npm run version 或 npx changeset version
• commit: 版本更新的提交信息
• title: Version PR 的标题

自动化流程

1. 每次推送到 main 分支触发工作流
2. Action 检查是否有 changeset 文件
3. 如果有 changeset，创建/更新 Version PR
4. 如果没有 changeset（说明已合并 Version PR），发布包

工程化最佳实践

Changeset 文件规范

• 每个 PR 必须包含至少一个 changeset
• Changeset 摘要应清晰描述变更内容和影响
• 使用 imperative mood（祈使语气）描述变更

版本策略

• 库包遵循 SemVer 语义化版本
• 应用包可以使用 CalVer（日历版本）或 Git 版本
• 预发布版本使用 pre 命令管理

发布审核

• Version PR 必须经过代码审查
• 确保 changelog 内容准确
• 验证版本号正确

性能与安全

性能特点

性能优势

• Changeset 文件读写操作轻量，不影响开发速度
• 版本计算和依赖解析在内存中完成，速度较快
• 支持增量处理，只处理有变更的包

性能优化

• 大型 monorepo（100+ 包）建议使用 turbo 或 nx 并行构建
• 使用 ignore 配置忽略不需要版本管理的包
• 预发布版本使用 snapshot releases 减少版本更新开销

安全注意事项

NPM 发布安全

• 使用 NPM_TOKEN 环境变量，不要在代码中硬编码
• 在 GitHub Actions 中使用 OIDC（OpenID Connect）替代长期 token
• 启用 npm 2FA（双因素认证）保护账号

Changeset 文件安全

• Changeset 文件应包含在版本控制中
• 不要在 changeset 中暴露敏感信息
• 定期清理 .changeset/ 目录中的临时文件

发布权限

• 使用 access: "restricted" 控制私有包发布
• 配置 npm 组织权限，限制可发布包的范围
• 审查所有 changeset 文件，防止恶意变更

已知性能瓶颈

• 超大型 monorepo（500+ 包）版本计算可能较慢
• 依赖关系复杂时，内部依赖更新耗时增加
• Changelog 生成在大量历史版本时可能变慢

技术对比

Changesets vs semantic-release

选择建议：

• Monorepo + 多包独立版本 → Changesets
• 单包 + 完全自动化 → semantic-release
• 需要发布审核 → Changesets
• 已采用 Conventional Commits → semantic-release

Changesets vs release-it

选择建议：

• Monorepo 多包 → Changesets
• 小团队或个人项目 → release-it
• 需要精细控制发布时机 → release-it
• 需要团队协作和审核 → Changesets

Changesets vs Lerna

选择建议：

• 纯版本管理 → Changesets
• 完整 monorepo 管理（旧项目） → Lerna
• 新项目 → Changesets + Turbo/Nx

最佳实践

生产环境最佳实践

1. Changeset 文件规范

---
"@my-org/ui": minor
"@my-org/utils": patch
---
 
添加了新的 Button 组件变体，并优化了工具函数的性能

• 使用清晰的包名（包括 scope）
• 准确选择版本类型
• 摘要描述具体变更内容和影响

2. 配置优化

{
  "access": "public",
  "baseBranch": "main",
  "updateInternalDependencies": "patch",
  "ignore": ["@my-org/docs", "@my-org/playground"],
  "changelog": ["@changesets/changelog-github", { "repo": "my-org/my-repo" }]
}

• 忽略文档和示例包
• 使用 @changesets/changelog-github 生成带 PR 链接的 changelog
• 设置正确的 baseBranch

3. CI/CD 配置

# 强制 PR 必须包含 changeset
- name: Check for changeset
  run: |
    if ! npx changeset status --since=origin/main; then
      echo "❌ PR 必须包含 changeset 文件"
      exit 1
    fi

• 在 PR 检查中强制要求 changeset
• 使用 Changeset Bot 自动提醒
• Version PR 必须经过代码审查

4. 预发布管理

# 进入预发布模式
npx changeset pre enter beta
 
# 正常创建 changeset 和版本更新
npx changeset
npx changeset version
 
# 退出预发布模式
npx changeset pre exit

• 预发布版本自动添加后缀（如 1.0.0-beta.0）
• 预发布期间不合并到主版本
• 退出预发布模式后生成正式版本

5. 快照发布

# 创建快照版本
npx changeset version --snapshot
 
# 发布快照
npx changeset publish --tag snapshot

• 快照版本基于 commit hash
• 适合频繁发布的场景
• 不会更新正式版本

常见陷阱

1. 忘记添加 changeset

• 问题：PR 合并后没有 changeset，包不会发布
• 解决：使用 Changeset Bot 自动检查

2. 版本号选择不当

• 问题：过度使用 major 版本，导致用户频繁升级
• 解决：严格遵循 SemVer，breaking change 才用 major

3. 忽略内部依赖更新

• 问题：包 A 依赖包 B，B 升级后 A 的 package.json 未更新
• 解决：设置 updateInternalDependencies: "patch"

4. 预发布版本混乱

• 问题：预发布版本和正式版本混用
• 解决：明确区分 pre 和正式版本，及时退出预发布模式

5. Changelog 内容不准确

• 问题：changeset 摘要过于简单，changelog 可读性差
• 解决：要求开发者编写详细的变更摘要

推荐模式

模式 1：标准开源项目

# 开发阶段
git checkout -b feature/new-feature
# 开发并创建 changeset
npx changeset
git add .
git commit -m "feat: 添加新特性"
git push
 
# 发布阶段（CI 自动处理）
# 1. 合并 PR 后自动创建 Version PR
# 2. 审查并合并 Version PR
# 3. 自动发布到 npm

模式 2：企业级严格审核

# 开发阶段
npx changeset
git commit -m "feat: 添加功能"
 
# 版本更新
npx changeset version
git commit -m "chore: bump versions"
 
# 代码审查
# 1. 审查 Version PR（检查版本号和 changelog）
# 2. 合并 Version PR
 
# 发布
npx changeset publish
git push --follow-tags

模式 3：持续发布

# 使用快照发布
npx changeset version --snapshot
npx changeset publish --tag snapshot
 
# 每个 commit 都生成快照版本
# 适合频繁测试和早期反馈

技术局限与边界

已知限制

1. 不支持非 JavaScript 生态

• Changesets 专为 npm/pnpm/yarn 生态设计
• 不支持其他包管理器（如 Cargo、pip、Maven）
• 多语言 monorepo 需要额外工具配合

2. 依赖 Git 仓库

• 必须使用 Git 版本控制
• 依赖 git tags 和分支管理
• 不支持其他 VCS（如 SVN、Mercurial）

3. 两阶段流程的额外开销

• 需要合并两次 PR（功能 PR + Version PR）
• 发布周期较长
• 不适合需要即时发布的场景

4. 配置复杂度

• 大型 monorepo 配置复杂（fixed、linked、ignore）
• 预发布版本管理需要额外学习
• 自定义 changelog 格式需要了解内部 API

5. 性能瓶颈

• 超大型 monorepo（500+ 包）版本计算慢
• 依赖关系复杂时性能下降
• Changelog 生成在大量历史版本时变慢

不适用场景

1. 单包项目

• Changesets 主要为 monorepo 设计
• 单包项目使用 semantic-release 或 release-it 更简单
• 过度设计，增加不必要的复杂度

2. 非 JavaScript 生态

• Changesets 不支持其他语言生态
• 多语言 monorepo 需要混合工具（如 Changesets + 其他版本管理工具）

3. 完全自动化发布

• Changesets 需要人工创建 changeset 和审核 Version PR
• 追求完全自动化应选择 semantic-release

4. 即时发布需求

• 两阶段流程不适合需要即时发布的场景
• 快照发布可减少延迟，但仍需额外步骤

5. 非 Git 版本控制

• Changesets 依赖 Git 特性
• 不支持其他 VCS

权衡取舍

优势 vs 复杂度

• 优势：强大的 monorepo 支持、灵活的版本协调、两阶段审核
• 代价：配置复杂度、额外的 PR 合并步骤、学习曲线

自动化 vs 控制

• 优势：两阶段流程提供人工审核机会
• 代价：发布周期较长，不适合完全自动化

灵活性 vs 性能

• 优势：支持各种版本协调模式
• 代价：超大型 monorepo 性能瓶颈

迁移注意事项

从 semantic-release 迁移

1. 移除 semantic-release 配置
2. 安装 @changesets/cli 并初始化
3. 调整发布工作流（从单阶段到两阶段）
4. 培训团队成员创建 changeset

从 Lerna 迁移

1. 保留 lerna.json 中的依赖链接配置（或迁移到 changeset 配置）
2. 安装 @changesets/cli
3. 调整发布命令
4. 逐步移除 Lerna 的版本管理功能

迁移风险

• 历史版本号和 changelog 需要手动迁移
• 团队需要适应新的工作流程
• CI/CD 配置需要重新调整

学习资源

官方文档

• Changesets 官方网站 - https://changesets.dev
• 官方文档 - https://changesets-docs.vercel.app
  • 配置选项
  • 命令行参数
  • 添加 changeset
  • 固定包
  • 关联包
  • 预发布
  • 快照发布
  • 自动化
• GitHub 仓库 - https://github.com/changesets/changesets
  • 详细解释
  • 使用入门

教程

• Vercel Academy - Changesets for Versioning - https://vercel.com/academy/production-monorepos/changesets-versioning
  • 生产级 monorepo 版本管理教程
• Infinum Frontend Handbook - https://infinum.com/handbook/frontend/changesets
  • 前端团队使用 Changesets 的完整指南
• Think Through - Manage your versioning and changelogs using Changesets - https://thinkthroo.com/blog/manage-version-changelog
  • 从零开始学习 Changesets
• 掘金 - Changesets 一个强大而灵活的版本管理工具 - https://juejin.cn/post/7579093412331520010
  • 中文教程，详细介绍核心概念和使用
• 知乎 - 从零到一：实现 Changesets 自动化发版全流程 - https://zhuanlan.zhihu.com/p/25771848717
  • 中文教程，完整自动化工作流

社区资源

• Changesets GitHub Action - https://github.com/changesets/action
  • 官方 GitHub Action，自动化发布工作流
• Changeset Bot - https://github.com/apps/changeset-bot
  • GitHub Bot，自动检查 PR 是否包含 changeset
• Open Collective - https://opencollective.com/changesets
  • 赞助和支持 Changesets 项目
• YouTube 教程
  • Automate Package Versioning With Changesets CLI Tool
  • Version Your Packages with Changesets

2026 年现状

最新版本

稳定版本

• 2.31.0（2026 年 5 月）- 当前最新稳定版
• 包含大量 bug 修复和性能优化
• 支持 Node.js 22+

预发布版本

• 3.0.0-next.7（2026 年 7 月 1 日）- 最新预发布版
• v3 正在开发中，预计 2026 年中/晚正式发布
• v3 主要改进：性能优化、更好的 TypeScript 支持、简化配置

发展趋势

社区增长

• npm 周下载量约 300 万（2026 年）
• GitHub Stars 超过 12,100
• 成为 monorepo 版本管理的事实标准

生态扩展

• 与 Turbo、Nx 等构建工具深度集成
• 支持更多 monorepo 架构模式
• 社区贡献的 changelog 生成器不断增多

技术演进

• v3 版本正在开发，重点优化性能和易用性
• 更好的 TypeScript monorepo 支持
• 简化配置和工作流

社区活跃度

维护状态

• 积极维护，定期发布更新
• Atlassian 和 Thinkmill 持续赞助
• 社区贡献活跃（890+ commits，799+ forks）

问题响应

• 231 个 open issues
• 81 个 open pull requests
• 维护者响应及时

未来路线图

v3 版本计划

• 性能优化（特别是大型 monorepo）
• 简化的配置选项
• 更好的 TypeScript 支持
• 改进的依赖解析算法

长期愿景

• 成为 monorepo 版本管理的唯一解决方案
• 支持更多包管理器和生态
• 提供更强大的自动化工具

社区目标

• 增加贡献者和维护者
• 完善文档和教程
• 扩大在开源项目中的采用率