07-版本号规范语义化版本 X.Y.Z 适配SaaS系统与设备固件迭代前言软件版本号不就是随便起个名吗v1.0、v2.0、v1.0.3-fix、v1.0_final、v1.0_final_final……如果你见过这种版本号就知道这不是段子。版本号不是拍脑袋定的它背后有一套被业界广泛认可的标准——语义化版本控制Semantic Versioning简称 SemVer。本文讲清楚 SemVer 规范的每一段含义以及在 SaaS 系统和嵌入式设备固件两种场景下版本号应该怎么定。一、语义化版本控制SemVer规范1.1 版本号格式MAJOR.MINOR.PATCH X . Y . Z版本号由三段数字组成从左到右依次是主版本号X、次版本号Y、修订号Z。每一段都是非负整数不能前导零01.02.03是不合法的。例如1.4.2表示主版本 1次版本 4修订号 2。1.2 三段含义与递增规则段名称何时递增兼容性影响X主版本号 (MAJOR)做了不兼容的 API 修改不兼容需迁移Y次版本号 (MINOR)新增了向下兼容的功能兼容可选择升级Z修订号 (PATCH)做了向下兼容的 Bug 修复兼容建议立即升级递增规则有一条关键细节当某一段递增时它右边的所有段归零。1.4.2→ 新增功能 →1.5.0Y1Z 归零1.5.0→ 修复Bug →1.5.1Z11.5.1→ 不兼容修改 →2.0.0X1Y和Z归零1.3 预发布与构建元数据SemVer 还支持附加标识用于标记开发阶段1.0.0-alpha.1 # alpha 阶段第1版 1.0.0-beta.2 # beta 阶段第2版 1.0.0-rc.1 # release candidate 第1版 1.0.0 # 正式版无附加标识 1.0.0build.123 # 构建元数据不影响版本优先级优先级从低到高1.0.0-alpha 1.0.0-beta 1.0.0-rc.1 1.0.01.4 判断兼容不兼容的核心问题每次发版前问自己三个问题改了 API 的签名吗删了参数、改了返回类型、移除了接口→ 是X 递增加了新功能但没改老接口→ 是Y 递增只是修了 Bug接口没变→ 是Z 递增二、SaaS 系统版本号策略2.1 SaaS 版本号的挑战SaaS 系统通常是多租户的所有租户共用一套代码。版本迭代频繁API 面向多个端Web、APP、设备端兼容性管理尤为关键。2.2 API 兼容性规则以无人零售 SaaS 平台为例API 版本号和系统版本号是两套东西系统版本号v2.3.1描述整个平台的发布版本API 版本号/api/v1/device/list中的v1描述接口契约版本API 兼容性策略变更类型处理方式版本号影响新增接口直接加不影响老接口Y 递增接口新增返回字段可选向下兼容老客户端忽略即可Y 递增接口删除字段或改类型起新版本/api/v2/xxx老版本保留过渡X 递增接口删除先标记 deprecated过渡期后在新大版本移除X 递增2.3 实际版本号示例v1.0.0 平台首个正式版包含设备管理、商品管理基础功能 v1.1.0 新增库存盘点功能API 向下兼容 v1.1.1 修复盘点接口在设备离线时的空指针异常 v1.2.0 新增无人售货柜远程开门功能 v2.0.0 设备注册接口重构返回格式变更不兼容API 升级 /api/v2/device/register v2.1.0 新增 AI 商品识别结果回调接口2.4 多租户灰度发布SaaS 系统发版不是一锤子买卖需要灰度v2.1.0-rc.1 内部测试租户先跑 v2.1.0-rc.2 修复测试反馈后扩大到10%租户 v2.1.0 全量发布灰度期间如果发现问题修完发 rc.2不影响正式版号v2.1.0的干净性。三、设备固件版本号策略3.1 固件版本号的特殊挑战和 SaaS 系统不同设备固件有硬件兼容性的额外约束同一个型号设备可能分批次生产硬件版本不同固件刷到设备上一旦出问题可能直接变砖OTA空中升级需要版本号来判断哪些设备需要升级3.2 固件版本号结构在标准 SemVer 三段基础上固件版本号建议增加硬件兼容标识X.Y.Zhw.硬件版本号例如1.0.0hw.rk3568-v1.2 适用于 RK3568 主板 v1.2 版本的固件 1.0.0hw.rk3568-v1.3 适用于 RK3568 主板 v1.3 版本的固件 2.0.0hw.stm32f4-v1.0 适用于 STM32F4 主板 v1.0 版本的固件构建元数据段后面不影响版本优先级比较但能精确定位固件对应的硬件批次。3.3 硬件兼容性判断规则固件变更硬件兼容版本号影响修复传感器读数Bug同硬件版本内Z 递增新增离线缓存功能同硬件版本内Y 递增适配新批次硬件新传感器型号新增硬件版本标识Y 递增 hw 更新重构通信协议旧固件无法对接不兼容X 递增3.4 OTA 升级版本号策略设备 OTA 中心需要一个升级规则典型策略当前固件: 1.2.0hw.rk3568-v1.2 可用固件: 1.2.1hw.rk3568-v1.2 → 可升级Z 递增patch 级别 可用固件: 1.3.0hw.rk3568-v1.2 → 可升级Y 递增minor 级别向下兼容 可用固件: 2.0.0hw.rk3568-v1.2 → 需人工确认X 递增major 级别不兼容 可用固件: 1.3.0hw.rk3568-v1.3 → 不升级硬件版本不匹配3.5 固件版本号实战示例1.0.0hw.rk3568-v1.0 初版固件基础功能设备注册、心跳、开关门 1.0.1hw.rk3568-v1.0 修复心跳上报偶发丢包问题 1.1.0hw.rk3568-v1.0 新增重力传感器数据采集功能 1.1.0hw.rk3568-v1.1 适配新批次硬件传感器型号变更 1.2.0hw.rk3568-v1.1 新增 AI 摄像头图像采集与上传功能 2.0.0hw.rk3568-v1.1 通信协议重构MQTT 替换为自定义 TCP 协议不兼容四、版本号管理工具4.1 Maven 版本管理Java 项目通过pom.xml管理版本号groupIdcom.alspd/groupIdartifactIddevice-gateway/artifactIdversion1.2.0/version发版时打 Taggittag v1.2.0gitpush origin v1.2.04.2 standard-version 自动化管理Node.js 项目或需要自动生成版本号的场景# 自动根据提交记录递增版本号、生成CHANGELOG、打Tagnpx standard-version# 手动指定版本类型npx standard-version --release-as major# X 递增npx standard-version --release-as minor# Y 递增npx standard-version --release-as patch# Z 递增五、常见误区误区正解版本号越大越牛版本号只反映兼容性不是质量评分修复Bug也递增Y只要不加功能只增 Z发了2.0.0还能往1.x加功能1.x 分支只能修 Bug新功能进 2.x预发布版可以随便用alpha/beta/rc 有明确优先级不能混用设备固件不用管兼容性硬件变砖的代价远大于软件回滚总结版本号不是装饰品它是兼容性契约。场景核心约束版本号策略SaaS 系统API 兼容性X 不兼容 / Y 兼容新功能 / Z 修Bug设备固件硬件兼容性 通信协议兼容性三段 hw 构建元数据标识一句话原则不兼容升大版本兼容加功能升中版本只修Bug升小版本。把这个刻在脑子里版本号就再也不会变成v1.0_final_final_v2了。 
长河君 · 2026/8/11 19:59:46 · 阅读 1.2k 07-版本号规范：语义化版本 X.Y.Z 适配SaaS系统与设备固件迭代
07-版本号规范语义化版本 X.Y.Z 适配SaaS系统与设备固件迭代前言软件版本号不就是随便起个名吗v1.0、v2.0、v1.0.3-fix、v1.0_final、v1.0_final_final……如果你见过这种版本号就知道这不是段子。版本号不是拍脑袋定的它背后有一套被业界广泛认可的标准——语义化版本控制Semantic Versioning简称 SemVer。本文讲清楚 SemVer 规范的每一段含义以及在 SaaS 系统和嵌入式设备固件两种场景下版本号应该怎么定。一、语义化版本控制SemVer规范1.1 版本号格式MAJOR.MINOR.PATCH X . Y . Z版本号由三段数字组成从左到右依次是主版本号X、次版本号Y、修订号Z。每一段都是非负整数不能前导零01.02.03是不合法的。例如1.4.2表示主版本 1次版本 4修订号 2。1.2 三段含义与递增规则段名称何时递增兼容性影响X主版本号 (MAJOR)做了不兼容的 API 修改不兼容需迁移Y次版本号 (MINOR)新增了向下兼容的功能兼容可选择升级Z修订号 (PATCH)做了向下兼容的 Bug 修复兼容建议立即升级递增规则有一条关键细节当某一段递增时它右边的所有段归零。1.4.2→ 新增功能 →1.5.0Y1Z 归零1.5.0→ 修复Bug →1.5.1Z11.5.1→ 不兼容修改 →2.0.0X1Y和Z归零1.3 预发布与构建元数据SemVer 还支持附加标识用于标记开发阶段1.0.0-alpha.1 # alpha 阶段第1版 1.0.0-beta.2 # beta 阶段第2版 1.0.0-rc.1 # release candidate 第1版 1.0.0 # 正式版无附加标识 1.0.0build.123 # 构建元数据不影响版本优先级优先级从低到高1.0.0-alpha 1.0.0-beta 1.0.0-rc.1 1.0.01.4 判断兼容不兼容的核心问题每次发版前问自己三个问题改了 API 的签名吗删了参数、改了返回类型、移除了接口→ 是X 递增加了新功能但没改老接口→ 是Y 递增只是修了 Bug接口没变→ 是Z 递增二、SaaS 系统版本号策略2.1 SaaS 版本号的挑战SaaS 系统通常是多租户的所有租户共用一套代码。版本迭代频繁API 面向多个端Web、APP、设备端兼容性管理尤为关键。2.2 API 兼容性规则以无人零售 SaaS 平台为例API 版本号和系统版本号是两套东西系统版本号v2.3.1描述整个平台的发布版本API 版本号/api/v1/device/list中的v1描述接口契约版本API 兼容性策略变更类型处理方式版本号影响新增接口直接加不影响老接口Y 递增接口新增返回字段可选向下兼容老客户端忽略即可Y 递增接口删除字段或改类型起新版本/api/v2/xxx老版本保留过渡X 递增接口删除先标记 deprecated过渡期后在新大版本移除X 递增2.3 实际版本号示例v1.0.0 平台首个正式版包含设备管理、商品管理基础功能 v1.1.0 新增库存盘点功能API 向下兼容 v1.1.1 修复盘点接口在设备离线时的空指针异常 v1.2.0 新增无人售货柜远程开门功能 v2.0.0 设备注册接口重构返回格式变更不兼容API 升级 /api/v2/device/register v2.1.0 新增 AI 商品识别结果回调接口2.4 多租户灰度发布SaaS 系统发版不是一锤子买卖需要灰度v2.1.0-rc.1 内部测试租户先跑 v2.1.0-rc.2 修复测试反馈后扩大到10%租户 v2.1.0 全量发布灰度期间如果发现问题修完发 rc.2不影响正式版号v2.1.0的干净性。三、设备固件版本号策略3.1 固件版本号的特殊挑战和 SaaS 系统不同设备固件有硬件兼容性的额外约束同一个型号设备可能分批次生产硬件版本不同固件刷到设备上一旦出问题可能直接变砖OTA空中升级需要版本号来判断哪些设备需要升级3.2 固件版本号结构在标准 SemVer 三段基础上固件版本号建议增加硬件兼容标识X.Y.Zhw.硬件版本号例如1.0.0hw.rk3568-v1.2 适用于 RK3568 主板 v1.2 版本的固件 1.0.0hw.rk3568-v1.3 适用于 RK3568 主板 v1.3 版本的固件 2.0.0hw.stm32f4-v1.0 适用于 STM32F4 主板 v1.0 版本的固件构建元数据段后面不影响版本优先级比较但能精确定位固件对应的硬件批次。3.3 硬件兼容性判断规则固件变更硬件兼容版本号影响修复传感器读数Bug同硬件版本内Z 递增新增离线缓存功能同硬件版本内Y 递增适配新批次硬件新传感器型号新增硬件版本标识Y 递增 hw 更新重构通信协议旧固件无法对接不兼容X 递增3.4 OTA 升级版本号策略设备 OTA 中心需要一个升级规则典型策略当前固件: 1.2.0hw.rk3568-v1.2 可用固件: 1.2.1hw.rk3568-v1.2 → 可升级Z 递增patch 级别 可用固件: 1.3.0hw.rk3568-v1.2 → 可升级Y 递增minor 级别向下兼容 可用固件: 2.0.0hw.rk3568-v1.2 → 需人工确认X 递增major 级别不兼容 可用固件: 1.3.0hw.rk3568-v1.3 → 不升级硬件版本不匹配3.5 固件版本号实战示例1.0.0hw.rk3568-v1.0 初版固件基础功能设备注册、心跳、开关门 1.0.1hw.rk3568-v1.0 修复心跳上报偶发丢包问题 1.1.0hw.rk3568-v1.0 新增重力传感器数据采集功能 1.1.0hw.rk3568-v1.1 适配新批次硬件传感器型号变更 1.2.0hw.rk3568-v1.1 新增 AI 摄像头图像采集与上传功能 2.0.0hw.rk3568-v1.1 通信协议重构MQTT 替换为自定义 TCP 协议不兼容四、版本号管理工具4.1 Maven 版本管理Java 项目通过pom.xml管理版本号groupIdcom.alspd/groupIdartifactIddevice-gateway/artifactIdversion1.2.0/version发版时打 Taggittag v1.2.0gitpush origin v1.2.04.2 standard-version 自动化管理Node.js 项目或需要自动生成版本号的场景# 自动根据提交记录递增版本号、生成CHANGELOG、打Tagnpx standard-version# 手动指定版本类型npx standard-version --release-as major# X 递增npx standard-version --release-as minor# Y 递增npx standard-version --release-as patch# Z 递增五、常见误区误区正解版本号越大越牛版本号只反映兼容性不是质量评分修复Bug也递增Y只要不加功能只增 Z发了2.0.0还能往1.x加功能1.x 分支只能修 Bug新功能进 2.x预发布版可以随便用alpha/beta/rc 有明确优先级不能混用设备固件不用管兼容性硬件变砖的代价远大于软件回滚总结版本号不是装饰品它是兼容性契约。场景核心约束版本号策略SaaS 系统API 兼容性X 不兼容 / Y 兼容新功能 / Z 修Bug设备固件硬件兼容性 通信协议兼容性三段 hw 构建元数据标识一句话原则不兼容升大版本兼容加功能升中版本只修Bug升小版本。把这个刻在脑子里版本号就再也不会变成v1.0_final_final_v2了。