Atlassian Changesets 命令行工具完全指南

Atlassian Changesets 命令行工具完全指南

changesets 项目地址: https://gitcode.com/gh_mirrors/cha/changesets

前言

Atlassian Changesets 是一个专为现代 JavaScript 项目设计的版本管理和发布工具，特别适合 monorepo 项目结构。本文将深入解析 Changesets 提供的所有命令行工具，帮助开发者掌握这个强大的版本控制利器。

核心命令概览

Changesets 提供了 7 个主要命令，构成了完整的版本管理流程：

1. init - 初始化 Changesets 配置
2. add - 创建变更记录
3. version - 更新版本号和变更日志
4. publish - 发布到 npm
5. status - 查看变更状态
6. pre - 预发布模式管理
7. tag - 创建 Git 标签

命令详解

1. 初始化命令：init

changeset init

这是项目配置的第一步，会在项目中创建 .changeset 目录，包含：

• 配置文件 (config.js)
• 说明文档 (README.md)

最佳实践：项目初始化时只需执行一次此命令。

2. 变更记录命令：add

changeset add
# 或简写
changeset

这是开发者最常用的命令，用于记录代码变更。执行后会交互式询问：

1. 影响哪些包
2. 版本号变更类型 (major/minor/patch)
3. 变更摘要说明

生成的变更文件包含 YAML 头信息和 Markdown 内容，例如：

---
"@changesets/cli": major
---

重大变更说明...

实用选项：

• --empty：创建空变更记录（用于 CI 等场景）
• --open：在编辑器中打开生成的变更文件

3. 版本更新命令：version

changeset version

此命令执行以下操作：

• 根据变更记录更新包版本号
• 更新依赖关系
• 生成变更日志

重要选项：

• --ignore：跳过指定包的版本更新
• --snapshot：创建临时测试版本（非正式发布）

注意事项：建议在运行 publish 命令前，先将 version 的变更合并到主分支。

4. 发布命令：publish

changeset publish

发布流程的核心命令，功能包括：

• 检查并发布未发布的包版本
• 自动适配 npm/pnpm 等包管理器
• 创建 Git 标签

关键选项：

• --otp：提供 npm 双因素认证令牌
• --tag：指定发布标签（非 latest）

发布后建议：执行 git push --follow-tags 推送标签

5. 状态查询命令：status

changeset status

查看当前变更集状态，支持：

• --verbose：显示详细信息
• --output：输出 JSON 格式状态
• --since：基于特定 Git 引用查询

6. 预发布模式命令：pre

changeset pre enter next  # 进入预发布模式
changeset pre exit        # 退出预发布模式

用于管理预发布流程，需要配合常规发布命令使用。

重要提示：预发布功能较为复杂，建议充分理解后再使用。

7. 标签创建命令：tag

changeset tag

独立创建 Git 标签，格式为 pkg-name@version-number（单包项目为 v1.0.0 格式）。

工作流建议

标准 Changesets 工作流通常包含以下步骤：

1. 开发者在功能分支使用 changeset add 记录变更
2. 合并到主分支后，维护者运行 changeset version
3. 检查版本变更无误后，执行 changeset publish
4. 最后推送标签：git push --follow-tags

常见场景处理

1. 部分发布：使用 --ignore 选项跳过特定包
2. 测试发布：使用 --snapshot 创建临时版本
3. 自动化集成：利用 status --output 输出 JSON 供 CI 使用
4. 预发布流程：结合 pre 命令管理 beta/rc 版本

总结

Atlassian Changesets 通过这套命令行工具，为 JavaScript 项目特别是 monorepo 提供了完整的版本管理解决方案。掌握这些命令的使用方法和适用场景，能够显著提升项目的版本管理效率和发布质量。建议团队根据实际需求，制定适合的 Changesets 使用规范和工作流程。

changesets 项目地址: https://gitcode.com/gh_mirrors/cha/changesets