Changesets Snapshot Releases 实战指南不升版本号的临时发布方案【免费下载链接】changesets A tool to manage versioning and changelogs with a focus on monorepos项目地址: https://gitcode.com/gh_mirrors/ch/changesetsSnapshot Releases快照发布是 Changesets 提供的一种为测试而发布、却不动正式版本号的发布方式通过组合version --snapshot与publish --tag两个命令把 PR 预览版、main分支的 nightly 版发布到 npm得到形如0.0.0-bulbasaur-20250922031500的版本号。读完本文你将掌握快照发布的完整命令链、自定义版本后缀与 dist-tag 的正确用法、--no-git-tag等安全选项以及快照分支的正确处置方式并理解其底层版本合成逻辑。什么是 Snapshot Release在常规发布流程中changeset version会根据 changeset 文件计算下一个语义化版本号如1.0.0→1.1.0changeset publish随后把新版本发布到 npm。而快照发布的区别在于它只用于测试不推进正式版本号。执行快照发布后被 changeset 覆盖的包会被发布为一个类似0.0.0-{tag}-{datetime}的版本。这样的版本不会占用真实的 semver 版本位避免污染正式发布记录可以在 PR 中作为预览版被安装验证也可用于 nightly 自动构建整个过程可以完全跑在 CI 中自动化完成。发布快照需要同时使用两个被改造过的命令version带--snapshot和publish带--tag。两个命令先后执行完毕后changesets 管理的包就会以一个临时版本号出现在 npm 上。备选方案如果你只是想快速获得可安装的预览包也可以借助 pkg.pr.new 之类的第三方服务——它们发布到自己的 registry以临时发布的形式避免污染 npm 上的版本号和 tag。不过本文聚焦于 Changesets 自带的快照能力。起步创建 changeset 与专属分支快照发布的前置步骤和普通发布完全一样照常使用changeset add创建 changeset 文件写入.changeset目录方式与添加 changeset 一致准备好发布快照时创建一个专门用于快照发布的分支dedicated branch。这个专属分支的意义会在后文快照分支的处置一节中进一步说明——快照产生的版本变更不应该回流到主分支。版本号合成version --snapshot基本用法在专属分支上执行# pnpm $ pnpm changeset version --snapshot # npm $ npx changesets/cli version --snapshot # yarn $ yarn changeset version --snapshot这条命令会照常应用 changeset更新依赖范围、生成 changelog但不再使用计算出的下一个正式版本号而是把涉及包的版本全部设置为0.0.0-{datetime}其中{datetime}是执行命令时的时间戳。自定义快照标签如果你希望版本号带有可辨识的个性化片段例如用bulbasaur标识某次 PR 预览可以给--snapshot传入一个名字# pnpm $ pnpm changeset version --snapshot bulbasaur # npm $ npx changesets/cli version --snapshot bulbasaur # yarn $ yarn changeset version --snapshot bulbasaur此时版本号会变成0.0.0-bulbasaur-{datetime}。这个名字会成为 npm dist-tag 与版本号后缀方便团队成员按标签安装对应预览版。源码视角快照版本如何合成从源码看快照版本由packages/assemble-release-plan/src/index.ts中的getSnapshotSuffix与getSnapshotVersion两个函数完成。getSnapshotSuffix支持以下占位符详见 assemble-release-plan/src/index.ts占位符含义{tag}--snapshot传入的名字{datetime}ISO 时间戳去符号后的字符串如20250922031500{timestamp}Date.now()的毫秒时间戳{commit}当前 git 提交的完整 hash{commit-short}当前 git 提交 hash 的前 7 位当没有配置模板时后缀默认由tag与datetime拼合tag 为空则只保留 datetime。getSnapshotVersion则把基础版本固定为0.0.0再加上该后缀——选用0.0.0是有意为之如果沿用计算出的正式版本如1.0.0-beta.0附近使用^1.0.0-beta范围依赖的消费者可能被快照版抢占解析结果0.0.0前缀可以确保快照版永远不会与正式版本冲突源码注释见 assemble-release-plan/src/index.ts。version命令在快照模式下还有两个值得注意的行为见 cli/src/commands/version/index.ts强制关闭自动 commit即使配置了commit: true快照模式下也不会自动提交避免临时版本变更混入提交历史测试用例见 version.test.ts与 pre 模式互斥若当前处于 prerelease 模式pre enter之后直接运行--snapshot会报错退出需先changeset pre exit。更精细的控制快照模板与计算版本version命令还支持--snapshot-prerelease-template template参数用于完全自定义版本后缀效果与配置文件的snapshot.prereleaseTemplate一致参见 cli.md$ changeset version --snapshot pr#123 --snapshot-prerelease-template {tag}-{commit-short}在.changeset/config.json中快照行为由snapshot配置段控制schema 定义见 config/src/config.ts{ snapshot: { // 若为 true快照版本以计算出的正式版本基于 changeset 的 bump 类型为基础 // 而不是固定使用 0.0.0。注意这会使快照版可能进入消费者解析范围默认 false useCalculatedVersion: false, // 版本后缀模板可用占位符{commit}、{tag}、{datetime}、{timestamp} prereleaseTemplate: {tag}-{datetime} } }需要注意模板与参数的配套约束源码会在 getSnapshotSuffix 中校验模板里用了{tag}但--snapshot未传名字 → 报错{tag} placeholder is used without having a value defined!模板里没有{tag}但传了快照名 → 报错{tag} placeholder is missing...。这些边界情况均有对应测试覆盖见 version.test.ts。发布publish --tag 与 npm dist-tag版本号改写完毕后执行发布$ changeset publish --tag bulbasaur关键在于--tag标志它指定发布时使用的 npm dist-tag。使用它之后快照版本不会被标记为latest从而不会成为npm install your-package-name不指定版本时的默认安装结果。即便你在version --snapshot时没有设置快照名发布时也依然必须使用--tag例如changeset publish --tag snapshot——用任意一个随机名称即可核心目的是避免污染latest。⚠️ 重要提醒 快照发布必须始终携带 tag。如果省略--tag别人执行npm install your-package-name时就会默认装到快照版本——这几乎肯定不是你想要的结果。从 CLI 定义看publish命令的--tag name与--git-tag默认开启是独立选项见 cli/src/cli.ts发布逻辑在 commands/publish/index.ts 中会校验prerelease 模式下不允许自定义 tag且发布时会输出警告提示包将发布到非latesttag。跳过 git tag--no-git-tag快照发布通常不需要创建 git tag——这些版本是临时性的tag 只会造成仓库噪音。此时用$ changeset publish --no-git-tagpublish默认会为每个包创建pkg-nameX.X.X单包仓库为vX.X.X格式的 git tag参见 cli.md。--no-git-tag关闭这一行为快照发布不产生任何 tag而之后正常的稳定版发布仍会照常打 tag。这样你可以放心地在本地或 CI 中频繁发布快照而不会把临时 tag 推到远端。在源码层面publish的gitTag选项默认为true见 commands/publish/index.ts--no-git-tag即把该选项置为falsegit tag 的创建集中在发布成功之后统一执行commands/publish/index.ts。消费快照安装预览版本想让人测试你的快照时对方有两种安装方式。方式一按精确版本安装先把package.json里的依赖改到你刚发布的版本再执行安装或者直接使用安装命令# pnpm $ pnpm add your-package-name0.0.0-bulbasaur-{datetime} # npm $ npm install your-package-name0.0.0-bulbasaur-{datetime} # yarn $ yarn add your-package-name0.0.0-bulbasaur-{datetime}方式二按 dist-tag 安装由于发布时指定了 tag也可以用 tag 直接安装# pnpm $ pnpm add your-package-namebulbasaur # npm $ npm install your-package-namebulbasaur # yarn $ yarn add your-package-namebulbasaur按 tag 安装的优点是tag 一旦固定后续用同一 tag 发布的新快照团队成员无需改版本号即可持续获取最新预览版。快照分支的处置不要合并回主分支这是快照发布最容易踩坑、也最重要的一环。在绝大多数情况下普通version之后的改动应该合并回main分支。但快照恰恰相反——我们强烈建议不要把这次version --snapshot产生的变更 push 到任何分支更不要把它合并进计划合入main的分支。原因在于快照分支上的package.json版本号、changelog 等改动是临时测试产物只代表用于安装的快照状态并不代表仓库真实、正确的发布状态。如果你把0.0.0-bulbasaur-xxx这类版本合并回主分支主分支上就会残留错误的版本号下一次正式发布会被严重干扰。正确的做法是记下本次生成的版本号和使用的 tag然后丢弃这个分支上的改动。之后以主分支为基线创建新的快照分支再次执行version --snapshot与publish --tag流程即可。与 prerelease 模式的取舍如果你已经在用changeset pre enter的 prerelease 模式可以对照一下两种方案的差异prerelease 会进入持续的预发布状态版本号形如1.0.0-beta.0且会去掉很多安全护栏而快照发布流程更轻量、彼此独立每次快照都不影响正式版本轨道。如果你的诉求是给 PR / nightly 提供一个可安装的临时版本快照发布通常更合适如果是要维护一条长期存在的 beta 通道则考虑 prerelease 模式。总结快照发布是 Changesets 在正式发布之外提供的一条测试通道其完整链路为照常创建 changeset新建专属分支changeset version --snapshot [name]把版本改写为0.0.0-{name}-{datetime}可用--snapshot-prerelease-template或配置文件snapshot.prereleaseTemplate自定义后缀snapshot.useCalculatedVersion控制是否沿用计算版本changeset publish --tag name发布到非latest的 dist-tag并按需加--no-git-tag跳过 git tag测试方按精确版本号或 dist-tag 安装快照快照分支的改动留在本地不 push、不合并回主分支。这套流程可以完整放进 CIPR 合并或 nightly 定时任务触发时自动执行实现零人工介入的预览版本分发。相关命令的完整参数可继续查阅 CLI 文档配置项细节见配置文件文档自动化落地可参考自动化指南。【免费下载链接】changesets A tool to manage versioning and changelogs with a focus on monorepos项目地址: https://gitcode.com/gh_mirrors/ch/changesets创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考