基于 release 分支的内部 npm 包应如何管理版本?
建议采用什么方案?
每当包 P 发布的内容发生变化,都应使用一个新的、不可覆盖的版本号。项目 X 锁定经过验证的具体版本,由自动化更新依赖和 lockfile。
这套做法不要求 release 分支合入 master/main。分支隔离决定代码从哪里来,包版本决定构建使用哪一份产物,两者可以独立管理。
针对当前流程,可以采用:
- 在稳定阶段发布
5.2.2-rc.1、5.2.2-rc.2等预发布版本。 - 为每条发布线设置独立的 dist-tag,例如
release-5.2.2。 - 通过自动化把选定版本写入项目 X 的
package.json和package-lock.json。 - CI 使用
npm ci安装已锁定的依赖。
为什么不应反复发布同一个版本?
如果 P@5.2.2 今天和明天包含不同代码,版本号就无法准确标识构建输入。
不同环境可能因此拿到不同内容:已有安装可能继续使用旧文件,缓存可能保留旧产物;重新下载的包也可能与 lockfile 中记录的完整性信息不符,导致安装失败。排查问题时,仅知道“使用了 5.2.2”,也无法确定实际运行的是哪份代码。
私有 registry 是否允许删除后重新发布,取决于具体产品和配置。即使允许,这种操作仍会削弱可复现构建和回滚能力。公开 npm registry 也不能按“删除后即可复用版本号”的方式设计发布流程。
产品版本与包版本需要一致吗?
没有必要保持一致。
产品版本 5.2.2 可以依赖包 P 的某个独立版本。只要依赖关系记录明确,产品发布编号就不必承担包的全部版本管理职责。
如果选择遵循 Semantic Versioning,应先明确包 P 的对外接口,再根据兼容性变化决定版本:兼容的修复增加 PATCH,兼容的新功能增加 MINOR,不兼容的接口变化增加 MAJOR。这里的“对外”也包括内部消费者使用的接口。
PM 指定的产品版本号未必符合这些规则。如果继续让包版本跟随产品版本,应明确这是一项版本命名约定,不能仅凭三个数字就认定它符合 Semantic Versioning。
在正式版 5.2.2 尚未发布时,可以使用以下候选版本:
5.2.2-rc.1
5.2.2-rc.2
5.2.2-rc.3
5.2.2
原问题中的 rc.01、rc.02 应改成 rc.1、rc.2:SemVer 的纯数字预发布标识符不允许前导零。属于 5.2.2 的候选版本也应保持 5.2.2-rc.N 这一基础版本,而不是切换到 5.2.1-rc.N。
如果正式版 5.2.2 已经发布,修改代码后就需要分配新版本,不能继续把变更作为同一个正式版本发布。
如何使用 dist-tags?
dist-tag 可以作为某条发布线当前候选包的可移动指针。例如,假设包名是 @internal/p,在包 P 的发布分支中执行:
npm version 5.2.2-rc.1 --no-git-tag-version
npm publish --tag release-5.2.2
下一次发布可以执行:
npm version 5.2.2-rc.2 --no-git-tag-version
npm publish --tag release-5.2.2
这些命令假设私有 registry 和发布凭据已经配置完成。版本文件的提交由现有发布流程处理。
此时,两个版本都保留在 registry 中,release-5.2.2 指向最新发布的候选版本。每条长期发布线应使用自己的 tag,避免其他分支的发布改变这条分支的候选依赖。
dist-tag 本身会移动,不能替代依赖锁定。即使 package.json 写的是 tag,已有 lockfile 也不会因为 tag 更新就自动切换到新包;npm ci 会按 lockfile 安装。
项目 X 应如何更新依赖?
需要接收新候选包时,建议明确更新依赖,并提交两个依赖文件:
npm install --save-exact @internal/p@5.2.2-rc.2
也可以从发布线的 tag 选择当前候选包:
npm install --save-exact @internal/p@release-5.2.2
更新后,检查 package.json 中保存的具体版本,以及 package-lock.json 中记录的解析结果。正式构建执行:
npm ci
如果发布与依赖更新可能并发发生,自动化应直接传递本次发布的具体版本号,避免读取 tag 时,它已经被后续发布移动到另一个版本。
如何减少频繁更新带来的操作成本?
可以把依赖更新接入现有发布流水线,减少开发者逐次手工修改文件的工作。
一个可行流程是:
- 包 P 的对应 release 分支生成唯一版本号并发布。
- 发布任务将包版本传给依赖更新任务。
- 更新任务只修改项目 X 对应 release 分支的依赖声明和 lockfile。
- 运行该发布线需要的构建与测试,再按团队现有流程合入。
这个流程引入已经发布的指定依赖版本,不需要从主干合并其他代码。
项目 X 也不必接收包 P 发布的每个版本。若一天内有多个候选版本,可以只验证并接收选定的候选版本。更新提交记录了依赖变化,有助于定位回归;需要减少提交数量时,可以批量处理依赖更新。
多条长期分支共用同一个包名时,版本号必须统一分配,避免不同分支尝试发布相同版本。dist-tags 只能提供不同指针,不能隔离同名包的版本空间。
备注:内容仅供参考。
