开发工具CLI【免费下载链接】changesets A tool to manage versioning and changelogs with a focus on monorepos项目地址https://gitcode.com/gh_mirrors/ch/changesets点击查看免费下载本指南以仓库 docs/command-line-options.md 为骨架结合 packages/cli/src/cli.ts 及各个命令的源码实现系统讲解 changesets 命令行工具的全部命令与选项。读者将掌握从初始化、贡献者撰写 changeset、版本升级与发布到预发布模式与 git 标签生成的一整套 monorepo 版本管理操作并理解每个选项背后的安全护栏与底层逻辑。命令总览changesets 的四种核心交互changesets 的命令行是其最主要的交互方式。核心命令由 7 个构成init、add、version、publish、status、pre和git-tag其中publish-plan与pack是面向产物化发布流程的补充命令见 cli.ts。从 cli.ts 的注册代码可以看到每个命令的完整定义而官方站点 site/guide/cli.data.ts 甚至直接以编程方式运行cli.parse来动态生成各命令的--help文档确保站点文档与 CLI 实际行为严格同步。四个最重要的命令构成一条完整链路add贡献者用来记录这次改动影响了哪些包、属于什么级别的 semver 变更、变更摘要是什么version消费add生成的 changeset更新各包的版本号与 changelog并同步依赖关系publish把更新后的包发布到 npm 并创建 git 标签status查看当前仓库中尚未发布的 changeset 状态常用于 CI 检查。入门用户建议先阅读 intro-to-using-changesets.md 了解推荐的初始化与工作流。init初始化 changesetschangeset initinit会创建.changeset文件夹并生成两个文件一个 README说明.changeset目录的用途一个配置文件.changeset/config.json其中包含全部默认选项及对应注释说明每个选项的含义。该命令只需在项目初次接入 changesets 时运行一次。配置文件的完整字段说明可参考 config-file-options.md 与 packages/config/src/config.ts。add创建 changeset 的主要命令changeset add或者直接运行changesetadd是cac注册的默认命令通过.alias(!)实现见 cli.ts所以两种写法等价。它是绝大多数人日常使用的命令。交互式流程add会按顺序向你提出一系列问题选择要发布的包在多包仓库中会列出发生变更的包与未变更的包两组多选框实现见 createChangeset.ts该文件被 commands/add/index.ts 调用为每个包选择 semver 提升级别先选 major红色X.X.X再选 minor绿色X.X.X剩下的自动归为 patch见 createChangeset.ts。单包仓库则直接询问一次升级类型输入整个 changeset 的摘要默认通过命令行提示输入直接留空会打开外部编辑器撰写多行摘要createChangeset.ts确认最终展示将要生成的 changeset 内容确认后才写入。值得注意的安全提示当某个包要发布1.0.0之前的首个 major 版本时CLI 会额外要求确认是否真的要发布首个 major 版本createChangeset.ts防止仓库级大扫除误把包直接升到 1.0.0。生成的 changeset 文件确认后changeset 会被写成一个 Markdown 文件正文是摘要顶部 YAML front matter 记录要发布的包及其 semver 提升级别。例如对changesets/cli做 major 提升的 changeset 长这样--- changesets/cli: major --- A description of the major changes. If you want to modify this file after its generated, thats completely fine or if you want to write changeset files yourself, thats also fine.生成的文件位于.changeset/随机id.md。写入逻辑见 packages/write/src/index.ts解析逻辑见 packages/parse/src/index.ts。如果生成后想修改直接编辑文件即可甚至完全手写 changeset 文件也是被支持的。选项选项说明--empty创建一个不提升任何包的空 changeset通常只在 CI 要求没有 changeset 就不允许合并时使用--open创建完成后用外部编辑器打开该 changeset 文件实现见 commands/add/index.ts-m, --message text直接从命令行提供摘要跳过摘要输入环节--since ref基于指定的分支、标签或 git 引用如main或某个 commit hash检测变更的包用于填充 CLI 中的变更包列表--major pkg/--minor pkg/--patch pkg非交互式直接指定每个包的提升级别可逗号分隔、可重复传参空 changeset用--empty创建changeset --empty生成的文件内容为--- ---提交行为如果配置文件中设置了commit选项add会在写入 changeset 文件后将其git add并提交commands/add/index.ts否则只提示你自行提交。--since的适用场景在 gitflow 式多目标分支工作流中配置里的baseBranch无法覆盖所有情况时--since可以指定用哪个分支/标签/commit 作为变更检测基准。不传时默认回退到.changeset/config.json中的baseBranch值changeset add --sincedevelop从源码看--since传入getVersionableChangedPackagesutils/versionablePackages.ts用于识别自该 ref 以来发生变更的包并且这是尽力而为的逻辑——即使检测失败也只会输出警告不会阻塞创建 changesetcommands/add/index.ts。非交互选项在源码层面有校验传给--major/--minor/--patch的包名若在项目中不存在或同一包被同时传给多个级别选项会直接报错退出createChangeset.ts。version应用 changeset 更新版本号与 changelogchangeset versionversion是负责发布前一切文件改动的命令读取已存在的 changeset更新各包的版本号和依赖版本同时写入 changelog。它不会发布任何内容到 npm。官方建议在运行publish之前应先把version产生的改动合并回基础分支。--ignore pkg跳过部分包changeset version --ignore PACKAGE_NAME--ignore允许在发布时跳过指定包从而实现仓库的部分发布。在 monorepo 中被忽略的包所依赖的其他包、或其他包对被忽略包的依赖关系都会影响发布安全性因此ignore带两条强制安全护栏如果某 changeset 同时提到了被忽略的包和未被忽略的包发布将失败如果某个被忽略的包要求其依赖作为发布的一部分被同步更新发布也将失败。这些限制是为了保证仓库或已发布代码不会进入损坏状态。发布细节可参考 problems-publishing-in-monorepos.md。源码层面version对--ignore还有两条额外校验commands/version/index.ts与配置互斥如果.changeset/config.json中已配置ignore同时又传了--ignore会报错只能二选一包名校验传给--ignore的包名若不在项目中会提示可能拼写错误。此外--ignore的依赖检查会构建忽略 devDependencies 的依赖图commands/version/index.ts公开包若依赖被跳过的包但自身未被跳过会要求把该公开包也加入--ignore而私有包因不会发布到 npm可以安全依赖被跳过的包。--snapshot快照版本changeset version --snapshot--snapshot用于一种特殊的测试性发布它不会按当前 semver 区间更新版本而是创建带标签的临时版本。使用前务必阅读 snapshot-releases.md。从源码看commands/version/index.ts快照模式还支持--snapshot name为快照版本指定名称如--snapshot pr#123--snapshot-prerelease-template template自定义快照预发布版本号模板如使用{commit}、{commit-short}占位符会触发读取当前 commit id快照模式下自动禁用commit配置避免产生提交。快照模式与pre预发布模式互斥如果当前处于 pre 模式却执行--snapshot会直接报错并要求先changeset pre exitcommands/version/index.ts。version的核心流水线是readChangesets读取全部 changeset →readPreState读取 pre 状态 →assembleReleasePlan汇总发布计划 →applyReleasePlan写入 package.json 与 changelogcommands/version/index.ts。若没有任何未发布的 changeset命令会以警告退出。publish发布到 npm 并创建 git 标签changeset publish [--otp{token}]publish负责把变更发布到 npm并创建 git 标签。其工作方式逐个进入每个包检查其在 npm 上是否已存在package.json中记录的版本若不存在则执行发布。使用 pnpm 作为包管理器时工具会自动检测并改用pnpm publish包管理器检测逻辑见 commands/publish/getPublishTool.ts。关键前提publish假设最后一次提交就是发布提交因此在version与publish之间不要再提交任何改动。这两个命令刻意分离是为了让你有机会先核对发布改动是否准确。从 commands/publish/index.ts 可以看到publish的完整工作流先通过getPublishPlan计算哪些包需要发布/只打标签commands/publish-plan/getPublishPlan.ts再按依赖图分批发布发布顺序严格遵循包依赖图保证依赖先于依赖者发布。选项选项说明--otpcode提供 npm 一次性密码适用于开启认证写入的 npm 账户。未提供时 CLI 会交互式提示输入--tag name为发布的包使用指定 npm dist-tag 替代默认的latest用于测试/验证用途通常与快照发布配合见 snapshot-releases.md--from-pack-dir dir从打包输出目录发布与pack命令配合--git-tag是否为发布创建 git 标签默认true源码中还有一些值得了解的细节OTP 与 2FA在 TTY 环境下若无 OTP首个包会以顺序模式发布以探测是否需要交互认证若返回failed:needs-2fa会暂停并让用户完成交互式 2FA 后继续commands/publish/index.tsCI 环境非 TTY 环境如 CI直接走批量发布路径自定义 tag 限制pre 模式下或使用--from-pack-dir时不允许自定义--tag失败退出码若有任何包发布失败进程以退出码 1 结束commands/publish/index.ts。Git 标签保留发布时的 git 标签很有用它让后来者能定位到当时的代码。publish会自动生成标签但需要手动推送才能让远端可见。建议发布后执行git push --follow-tagsmonorepo 中标签格式为包名版本号单包仓库中则是v版本号如v1.0.0。标签生成逻辑见 commands/git-tag/utils.ts。status查看当前 changeset 状态changeset status [--verbose] [--output{filePath}] [--since{gitTag}]status展示当前存在的 changeset 信息。若包有改动但没有任何 changeset命令会以退出码1失败——这正是它可被用作 CI 检查的原因commands/status/index.ts。选项选项说明--verbose显示新版本号并给出对应 changeset 摘要的链接--output把 status 的 JSON 对象写入文件供其他工具如 CI消费--since只显示自某个分支或 git 标签如main或最新 commit hash以来的 changeset--output写入的是assembleReleasePlan生成的完整 release plan JSONcommands/status/index.ts其中包含按 major/minor/patch 分组、每个包的新版本号与对应 changeset 文件。--verbose模式下输出会额外附上- 新版本号及.changeset/id.md路径commands/status/index.ts。关于--since的 CI 用途虽然--since可以用于给 CI 增加 changeset 检查但官方并不推荐这样做——不是每个 PR 都需要 changeset。在 GitHub 上更推荐使用 changeset bot 来检测缺少 changeset 的 PR。注意在version或publish执行过程中运行status会失败。如果希望在版本提升和发布那一刻获取状态必须在运行version之前立即执行status。另外从源码看status还支持通过环境变量CHANGESETS_OUTPUT提供输出路径withEnvOptions见 cli.ts。pre进入与退出预发布模式changeset pre [exit|enter {tag}]pre命令本身不做任何版本操作它只负责切换预发布模式changeset pre enter next或其他 tag该 tag 会写入版本号并作为 npm dist-tag进入 pre 模式changeset pre exit退出 pre 模式。进入 pre 模式后按正常流程执行changeset version与changeset publish即可产出预发布版本。更多细节见 prereleases.md。源码对参数有严格校验cli.ts只接受enter或exit且enter必须携带 tag。底层通过changesets/pre包的enterPre/exitPre读写.changeset/pre状态文件在 pre 模式中再次enter、或非 pre 模式中exit都会报错commands/pre/index.ts。退出 pre 模式时CLI 会提示你检查.changeset/pre文件夹里的 changeset——它们将被用作正式版本的 changelog。警告预发布是一个非常复杂的特性changesets 为你提供的许多安全护栏在 pre 模式下会被移除。官方建议先通读 problems-publishing-in-monorepos.md并清楚如何进入与退出如果希望流程更简单也可以考虑用 snapshot-releases.md 的快照发布替代。git-tag仅为所有包创建 git 标签changeset git-taggit-tag为所有包的当前版本创建 git 标签等价于changeset publish创建的标签但不向 npm 发布任何内容实现见 commands/git-tag/index.ts标签命名规则见其 utils.ts。适用场景当用其他工具如pnpm publish -r替代 changesets 发布包时可以用git-tag补齐 git 标签。若已使用changeset publish则无需再运行git-tagpublish 已默认创建标签。标签格式monorepo 中为包名版本号基于每个包package.json的当前版本号单包仓库中标签为v版本号如v1.0.0。务必先运行changeset version再运行changeset git-tag确保标签基于更新后的版本号。从源码看git-tag会跳过配置中ignore的包以及privatePackages.tag配置不允许打标签的包commands/git-tag/index.ts。该命令存在旧别名changeset tag使用时会有弃用警告cli.ts。补充命令publish-plan与pack除上述 7 个命令外当前版本的 CLI 还提供两个面向先打包、后发布流程的命令cli.tschangeset publish-plan [-o, --output file]展示当前已就绪、可以发布或打标签的包列表可输出 JSON 到文件[experimental]标记changeset pack --out-dir dir [--from-publish-plan file]把可发布的包打包成 tarball 到指定目录可结合publish-plan的 JSON 输出使用--out-dir为必填项。这两个命令组合出发布前先本地打包审查产物的工作流最终产物可通过changeset publish --from-pack-dir dir发布。对应测试见 packages/cli/src/commands/publish-plan/tests与 packages/cli/src/commands/pack/tests。通用行为与内部实现要点命令解析框架CLI 基于cac构建cli.ts支持-v, --version与-h, --help参数归一化normalizeOptions会剔除单字符别名、展开逗号分隔的多值参数如--major pkg1,pkg2、并对重复出现的选项只取最后一个值cli.ts环境变量CHANGESETS_OUTPUT可为publish、status、git-tag、publish-plan等命令提供 JSON 输出路径退出码约定status在有变更却无 changeset时、version在无未发布 changeset时以及publish在发布失败时均以退出码 1 结束便于 CI 集成命令级联测试CLI 行为由 packages/cli/src/cli.test.ts 及各命令的__tests__目录覆盖站点文档则通过 site/guide/cli.data.ts 直接渲染真实--help输出。完整工作流串讲以最典型的 monorepo 场景为例把这 7 个命令串成一条可落地的主线接入首次使用运行changeset init生成.changeset目录与配置文件记录变更贡献者在每个 PR 中运行changeset add或changeset交互式选择包、升级级别并填写摘要CI 可用changeset status或 changeset bot检查是否遗漏版本升级发布日合并所有 changeset 后运行changeset version统一更新版本号与 changelog并提交需要部分发布时加--ignore需要测试版本时加--snapshot发布确认无误后运行changeset publish按依赖图分批发布到 npm 并生成 git 标签最后git push --follow-tags推送标签预发布/快照迭代测试阶段用changeset pre enter next 常规流程或直接用--snapshot生成带 tag 的临时版本正式发布前记得changeset pre exit。这套流程正是 intro-to-using-changesets.md 与 detailed-explanation.md 所描述的核心模型配合 command-line-options.md 中的每个选项即可在任意 monorepo 中建立起严谨、可审计的版本管理与发布体系。赞分享开发工具CLI【免费下载链接】changesets A tool to manage versioning and changelogs with a focus on monorepos项目地址https://gitcode.com/gh_mirrors/ch/changesets点击查看免费下载相关推荐MCP Registry mcp-publisher CLI 完全参考从 init、login 到 publish、status 的源码级解析MCP Registry mcp publisher CLI 完全参考从 init、login 到 publish、status 的源码级解析 mcp pub后端AI Agent工具调用Zola CLI 完全指南init、build、serve、check 四大命令的用法与源码级解析Zola CLI 完全指南init、build、serve、check 四大命令的用法与源码级解析 Zola 是一款以单个二进制内置一切为理念的静态站点生静态站点CLI开发工具Coolify 中的 shadcn CLI 完整命令参考init、apply、add、search 与预设机制解析Coolify 中的 shadcn CLI 完整命令参考init、apply、add、search 与预设机制解析 本文基于 Coolify 仓库中随 Age后端云原生容器编排运维DevOps创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考