PAYATHON 2026

基于 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 时,它已经被后续发布移动到另一个版本。

如何减少频繁更新带来的操作成本?

可以把依赖更新接入现有发布流水线,减少开发者逐次手工修改文件的工作。

一个可行流程是:

  1. 包 P 的对应 release 分支生成唯一版本号并发布。
  2. 发布任务将包版本传给依赖更新任务。
  3. 更新任务只修改项目 X 对应 release 分支的依赖声明和 lockfile。
  4. 运行该发布线需要的构建与测试,再按团队现有流程合入。

这个流程引入已经发布的指定依赖版本,不需要从主干合并其他代码。

项目 X 也不必接收包 P 发布的每个版本。若一天内有多个候选版本,可以只验证并接收选定的候选版本。更新提交记录了依赖变化,有助于定位回归;需要减少提交数量时,可以批量处理依赖更新。

多条长期分支共用同一个包名时,版本号必须统一分配,避免不同分支尝试发布相同版本。dist-tags 只能提供不同指针,不能隔离同名包的版本空间。

备注:内容仅供参考。