Semver 语义化版本速查指南：版本号、范围表达式与 npm 工程实践

Semver 语义化版本速查指南版本号、范围表达式与 npm 工程实践【免费下载链接】reference为开发人员分享快速参考备忘清单(速查表)项目地址: https://gitcode.com/jaywcjlove/referenceSemantic Versioning语义化版本简称 Semver是现代软件工程中管理版本号语义的通用规范它让1.2.3这样的版本号不只是一种标记而成为可被工具解析、可被团队约定的契约。本文以 docs/semver.md 为主体系统讲解 Semver 的三段式版本结构、主/次/修订号的含义、npm 生态中最常用的范围匹配语法^、~、连字符、通配符与组合范围并结合本仓库中package.json、npm、lerna 等文档交叉印证实际用法。读完本文你将能读懂并编写任何package.json中的版本约束准确判断^1.2.3与~1.2.3的区别并理解预发布版本在匹配规则中的边界行为。语义化版本标准介绍Semver 是一种语义版本控制规范其全称规范由 semver.org 发布用于回答版本号应该怎么涨、怎么表达兼容性这一核心问题。本仓库的 Semver 备忘清单 以速查表的形式浓缩了该规范及 npm 语义版本器的常用语法适合日常查表使用。语义版本控制规范文档(semver.org)npm 的语义版本器(npmjs.com)版本号三段式结构一个标准的语义化版本号由三部分组成主版本号(MAJOR).次版本号(MINOR).修订号(PATCH)各自代表不同的变更含义字段含义主版本号(MAJOR)当你做了不兼容的 API 修改时递增次版本号(MINOR)当你做了向下兼容的功能性新增时递增修订号(PATCH)当你做了向下兼容的问题修正时递增这一约定的价值在于版本号本身就携带了兼容性信息。依赖方只需看主版本号是否变化就能判断升级是否需要修改代码发布方只要遵守规则就不会在1.x内悄悄破坏 API。本仓库自身的版本管理即遵循该规范见根目录 package.json 中的version: 1.46.0字段docs/package.json.md 也明确说明version字段是包的当前版本严格遵循 Semantic Versioning 2.0.0 语义化版本规范。简单范围Simple Ranges在声明依赖时我们经常只需要表达某个版本之上/之下的简单约束这类写法称为简单范围1.2.3 1.2.3 1.2.3 1.2.3 1.2.3含义如下不带任何运算符如1.2.3等价于1.2.3只匹配精确版本1.2.3/1.2.3/1.2.3分别表示大于、小于、大于等于某个版本多个简单范围可用空格组合例如1.0.2 2.1.2表示大于等于 1.0.2 且小于 2.1.2。请注意后缀版本如1.2.3-rc1不匹配简单范围。也就是说1.2.3-rc1既不等于1.2.3也不满足1.2.3预发布版本拥有独立的匹配规则见下文预发布一节。范围Rangesnpm 语义版本器为依赖声明提供了一组更聪明的范围语法其中~和^是最常用的两个运算符。下表是速查清单中的完整对应关系范围描述Notes~1.2.3是1.2.3 1.3.0^1.2.3是1.2.3 2.0.0^0.2.3是0.2.3 0.3.0(0.x.x 是特殊的)^0.0.1是0.0.1(0.0.x 是特殊的)^1.2是1.2.0 2.0.0(像 ^1.2.0)~1.2是1.2.0 1.3.0(像 ~1.2.0)^1是1.0.0 2.0.0~1相同的1.x相同的1.*相同的1相同的*任何版本x相同的解读要点^caret表示兼容允许在不改变最左侧非零数字的前提下更新版本。因此^1.2.3允许升到1.9.9但不会跨入2.0.0。0.x.x是特殊情况按 Semver 约定0.x阶段意味着初始开发公共 API 尚未稳定。因此^0.2.3被收紧为0.2.3 0.3.0而^0.0.1直接被限定为0.0.1。~tilde表示相当接近只允许修订号PATCH级别的更新~1.2.3即1.2.3 1.3.0。省略写法^1、~1、1.x、1.*、1五种写法语义一致都表示1.0.0 2.0.0*与x表示任何版本。1.x与1.*的等价关系x是*的别名二者在范围表达中含义相同。在本仓库 docs/package.json.md 的dependencies示例中可以看到这些语法的真实组合用法{ dependencies: { colors: *, foo: 1.0.0 - 2.9999.9999, bar: 1.0.2 2.1.2, baz: 1.0.2 2.3.4, boo: 2.0.1, qux: 1.0.0 || 2.3.1 2.4.5 || 2.5.2 3.0.0, asd: http://asdf.com/asdf.tar.gz, til: ~1.2, elf: ~1.2.3, two: 2.x, thr: 3.3.x, lat: latest, dyl: file:./path/to/dyl, pla: https://github.com/user/project/tarball/branch, stu: git://github.com/user/project.git#commit-ish } }连字符范围Hyphen Ranges连字符范围用于表达从一个版本到另一个版本的闭区间约束范围描述1.2.3 - 2.3.4是1.2.3 2.3.4当某一侧只写了部分版本号时规则如下部分向右范围描述1.2.3 - 2.3是1.2.3 2.4.01.2.3 - 2是1.2.3 3.0.0部分向左范围描述1.2 - 2.3.0是1.2.0 - 2.3.0记忆口诀当右侧为部分例如2.3时假定缺失的部分为x例如2.3.x所以1.2.3 - 2.3实际是1.2.3 2.4.0上限把2.3.x整段包含进去如果左边是部分的例如1.2则假定缺少的部分为0例如1.2.0所以1.2 - 2.3.0等价于1.2.0 - 2.3.0。有效的语义版本并非所有字符串都是合法版本号。语义化版本允许在主.次.修订之后追加预发布标识符-prerelease与构建元数据meta以下均为有效的语义版本示例0.0.4 1.2.3 10.20.30 1.1.2-prereleasemeta 1.1.2meta 1.1.2meta-valid 1.0.0-alpha 1.0.0-beta 1.0.0-alpha.beta 1.0.0-alpha.beta.1 1.0.0-alpha.1 1.0.0-alpha0.valid 1.0.0-alpha.0valid 1.0.0-alpha-a.b-c-somethinglongbuild.1-aef.1-its-okay 1.0.0-rc.1build.1 2.0.0-rc.1build.123 1.2.3-beta 10.2.3-DEV-SNAPSHOT 1.2.3-SNAPSHOT-123 1.0.0 2.0.0 1.1.7 2.0.0build.1848 2.0.1-alpha.1227 1.0.0-alphabeta 1.2.3----RC-SNAPSHOT.12.9.1--.12788 1.2.3----R-S.12.9.1--.12meta 1.2.3----RC-SNAPSHOT.12.9.1--.12 1.0.00.build.1-rc.10000aaa-kk-0.1 99999999999999999999999.999999999999999999.99999999999999999 1.0.0-0A.is.legal观察这些示例可以提炼出几条规律数字可以很大如10.20.30、99999999999999999999999.999999999999999999.99999999999999999均合法预发布标识符用-连接可包含点号分隔的多段如alpha.beta.1段内可用连字符如a-b-c-somethinglong构建元数据用连接只出现在版本末尾如meta、build.1848且不参与版本优先级比较大小写敏感但合法10.2.3-DEV-SNAPSHOT、1.0.0-0A.is.legal都符合规范甚至1.2.3----RC-SNAPSHOT.12.9.1--.12这种奇形怪状但符合 ABNF 语法的版本也是有效的——这正是语义化版本号验证正则表达式存在的意义。清单末尾附有两条正则参考按编号提取语言的验证正则、按组名称提取语言的验证正则。组合范围实际工程的依赖约束往往不止一个区间可以通过**空格AND和双竖线||OR**组合出复杂的范围范围描述0.14 16和 (空格分隔)0.14.x \|\| 15.x.x或 (双竖线分隔)空格表示并且0.14 16要求版本同时满足0.14与16||表示或者0.14.x || 15.x.x表示匹配0.14.x或15.x.x任意一个区间二者可以自由嵌套例如上文dependencies示例中的qux: 1.0.0 || 2.3.1 2.4.5 || 2.5.2 3.0.0就是一个三段 OR 组合。本仓库 .github/workflows/ci.yml 中的发布流程也体现了版本语义的应用CI 通过create-tag-action创建版本标签再以steps.changelog.outputs.version作为 Docker 镜像的 tagwcjiang/reference:${version}进行发布可见语义化版本已贯通到标签 → 发布 → 镜像版本的自动化链路。解释四个高频符号/写法的语义速记范围描述^意思是兼容~意思是相当接近0.x.x用于初始开发1.x.x表示定义了公共 API实践含义依赖库主版本为1.x时^1.2.3可以放心使用——说明该库已经定义了公共 API次版本内的升级不会破坏兼容性依赖库处于0.x初始开发时即使使用^0.2.3也只会允许0.2.x范围内的更新避免被不兼容的0.3.0波及~1.2.3这类相当接近的约束适合对稳定性要求较高的场景仅接受补丁级更新。预发布预发布版本在版本号之后用-追加用于正式发布前的候选测试alpha、beta、rc 等1.2.3-prereleasebuild 1.1.2-prereleasemeta关于预发布需要记住两点预发布版本优先级低于对应正式版本1.0.0-alpha 1.0.0-beta 1.0.0-rc.1 1.0.0这是 Semver 规范规定的比较顺序预发布版本不满足普通范围匹配如前文简单范围所述1.2.3-rc1不匹配1.2.3或1.2.3这类普通范围。不过 docs/package.json.md 中提到一个 npm 的实际例外npm 允许预发布版本匹配未明确指定预发布的 semver 范围——例如1.4.0-rc.0可以匹配1.3.0这与典型的 semver 严格检查行为不同。这意味着npm install默认情况下也可能把预发布版本解析进来生产环境如需严格锁定应结合 lock 文件或精确版本声明。在 npm 生态中的实战运用Semver 范围语法在 npm 生态中无处不在本仓库的多个文档可以交叉印证1.package.json依赖声明docs/package.json.md 规定包的version字段必须严格遵循 Semantic Versioning 2.0.0dependencies、devDependencies、peerDependencies等字段中的版本值均使用 semver 范围语法例如devDependencies: { package-2: ^0.4.2 }、peerDependencies: { package-3: ^2.7.18 }overrides字段可以覆盖传递依赖的版本如foo: 1.0.0用于替换存在已知安全问题的依赖版本。2.npm install时的范围指定docs/npm.md 展示了如何在安装命令中直接声明版本约束npm i sax # NPM 包默认范围 npm i saxlatest # 指定标签 最新 npm i sax3.0.0 # 指定版本 3.0.0 npm i sax1 2.0 # 指定版本范围 npm i org/sax # 范围内的 NPM 包其中npm i sax1 2.0正是组合范围AND的实战应用。若想跳过范围运算符、以精确版本保存依赖可使用-E--save-exact参数——docs/npm.md 明确说明它将使用精确的版本进行配置而不是使用 npm 默认的 semver 范围运算符。3. 发布与升版本npm version version用于更改package.json中的版本号见 docs/npm.md在 monorepo 场景中docs/lerna.md 展示了lerna version patch这类 semver 关键字升版方式其中patch、minor、major、premajor、preminor、prepatch、prerelease都是标准的语义化版本递增关键字docs/lerna.md 也提醒--exact参数会在更新的包中精确指定依赖版本如1.0.1而不是默认的^semver 范围如^1.0.1——这与 npm 的-E参数思路一致。4. 一个直观的换算练习把本文的所有规则串起来package.json中常见的声明可以这样理解express: ^4.17.1 // 4.17.1 5.0.0允许次版本与修订号更新 lodash: ~4.17.21 // 4.17.21 4.18.0仅允许修订号更新 typescript: ^5.0.0 // 5.0.0 6.0.0 react: 17.0.0 18.0.0 // 显式双边界总结版本号即契约主.次.修订分别对应不兼容修改、兼容新增、兼容修复0.x 代表初始开发阶段范围语法有章可循^兼容、~接近、连字符定闭区间、x/*通配、空格 AND、||OR全部规则浓缩在 docs/semver.md 这张速查表中预发布要小心普通范围不匹配预发布版本但 npm 存在允许预发布匹配的例外贯穿工程全流程从 package.json 的依赖声明、npm install的版本参数到 lerna 的升版关键字与 CI 的标签发布语义化版本是贯穿始终的工程约定。【免费下载链接】reference为开发人员分享快速参考备忘清单(速查表)项目地址: https://gitcode.com/jaywcjlove/reference创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考