发布前夜,小周把依赖声明从 1.4.2 改成 ^1.4.2,想让补丁版本自动跟上。第二天构建失败,锁文件里多了一个 1.9.0,而那个版本删掉了他正在用的一个参数。他问我:^ 不是只放行小版本吗,怎么会跳到 1.9?
这不是工具算错,是范围符号的字面含义和他脑子里的版本规则没对上。类似的问题还有“预发布为什么不算”“区间和并集怎么写”,下面用三个问题拆开。
下面拿数据鱼API的「语义化版本范围匹配」服务当例子。它给一个版本号和一个范围表达式,返回
satisfied布尔值;边界怎么划,得先把语义说清。
^ 和 ~ 到底放行到哪一步?两个符号都要求不低于给定版本,差别在允许往上走多远。按 npm 的语义化版本约定:
范围 | 放行区间 | 记忆点 |
|---|---|---|
^1.2.3 | 大于等于 1.2.3,小于 2.0.0 | 锁主版本 |
^0.2.3 | 大于等于 0.2.3,小于 0.3.0 | 0.x 收窄到次版本 |
^0.0.3 | 大于等于 0.0.3,小于 0.0.4 | 0.0.x 只放补丁 |
~1.2.3 | 大于等于 1.2.3,小于 1.3.0 | 锁主版本和次版本 |
~1.2 | 大于等于 1.2.0,小于 1.3.0 | 缺省补丁按 0 处理 |
一句话记:^ 管到下一个主版本之前,~ 管到下一个次版本之前。1.9.0 落在 ^1.4.2 的区间里,所以小周看到的不是异常,而是他写宽了;想要只跟着补丁走,应该写 ~1.4.2。
数据鱼API的匹配端点支持 ^、~、>、>=、<、<=、= 七个操作符。文档的操作符清单里没有 x 或 * 通配写法,别把别家包管理器的习惯直接搬过来;写范围前先看清单,比收到 4002 再回头猜省事。
单边条件最省事:>=1.4.2 是一个下界,<2.0.0 是一个上界。要表达“大于等于 1.4.2 且小于 2.0.0”,按 npm 的写法是空格分隔的两个比较器。问题在于,文档只列出了七个操作符,没有明确写组合语法和并集符号,所以这类写法要以接口的实际返回为准。
稳妥的接入顺序是:先用一条真实请求试组合写法,返回 satisfied 就说明这套语法被接受;返回 4002 就退回单区间,在应用层用两次调用取“与”。并集同理,先试 ||(放进查询串时要编码成 %7C%7C),不被接受就两次调用取“或”。
需求 | 候选写法 | 接口不接受时 |
|---|---|---|
单边 | >=1.4.2 | 无需降级 |
有界区间 | >=1.4.2 <2.0.0 | 两次调用,结果取与 |
并集 | ^1.4.2 和 ^2.0.0 两条 | 两次调用,结果取或 |
数据鱼这个接口只回一个 satisfied,不告诉你命中了哪一段区间;把每次请求的 version、range、satisfied 一起记下来,组合写法是否生效才有证据。
^1.0.0?1.2.3-beta.1 是预发布版本。按 SemVer 的优先级,它低于同为核心版本的 1.2.3,排序大致是 1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-beta < 1.0.0-rc.1 < 1.0.0。npm 还有一条更细的规则:预发布版本只有在比较器组里存在同 major.minor.patch 的预发布比较器时才匹配。
所以 1.5.0-beta 不满足 ^1.0.0,而 1.2.3-beta 可以满足 >=1.2.3-alpha <2.0.0。构建号不参与比较,1.2.3+build.7 与 1.2.3 视为同一优先级。发布候选阶段用范围做门禁时,这条规则决定了 rc 版本会不会被自动放进来。
还有一个文档里容易漏看的细节:version 和 range 在参数表里都标着非必填,空请求的已验证示例返回 version 为 1、range 为 1、satisfied 为 true。参数漏传不会报错,会拿默认值算出一个通过。接入时把两个参数做成非空校验,别让“默认通过”混进发布门禁。
GET /api/semver-range/match?version=1.9.0&range=^1.4.2
GET /api/semver-range/match?version=1.9.0&range=~1.4.2范围表达式不是越宽越省心,也不是越窄越安全。它是一句写给未来的话:哪些变化可以接受,哪些必须停下来看一眼。应用项目锁精确版本,库项目才用范围,这条分工写进仓库说明,比在群里口头约定有用。
数据鱼API的匹配结果可以当边界测试的参照:主版本边界、0.x 边界、预发布边界各准备一组样本,每次改依赖声明先跑一遍。把 satisfied 当证据,不当结论,范围这件事就从争吵变成了流程。
以上操作符与
satisfied字段说明,整理自数据鱼API「语义化版本范围匹配」接口的公开文档;^ 与 ~ 的区间按 npm 语义化版本约定解释,文中版本为演示。
原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。
如有侵权,请联系 cloudcommunity@tencent.com 删除。