【嵌入式】嵌入式系统中的 SemVer 版本控制方案

嵌入式系统中的 SemVer 版本控制方案

在嵌入式系统开发中，采用 语义化版本控制（SemVer, Semantic Versioning） 能帮助团队清晰地管理 固件（Firmware） 、驱动（Driver） 和 软件（Software） 版本，确保兼容性和稳定性。

[**嵌入式系统中的 SemVer 版本控制方案**](#嵌入式系统中的 SemVer 版本控制方案)
- [**1. SemVer 版本号格式**](#1. SemVer 版本号格式)
- [**2. 嵌入式中的扩展规则**](#2. 嵌入式中的扩展规则)
- - [**2.1 额外的构建号（Build Metadata）**](#2.1 额外的构建号（Build Metadata）)
  - [**2.2 预发布版本（Pre-release）**](#2.2 预发布版本（Pre-release）)
  - [**2.3 特殊版本（修订号）**](#2.3 特殊版本（修订号）)
- [**3. 在 Git / CI/CD 中应用 SemVer**](#3. 在 Git / CI/CD 中应用 SemVer)
- - [**3.1 Git 标签（Git Tag）**](#3.1 Git 标签（Git Tag）)
  - [**3.2 GitHub Actions / GitLab CI 结合 SemVer**](#3.2 GitHub Actions / GitLab CI 结合 SemVer)
  - [**3.3 在固件中嵌入版本号**](#3.3 在固件中嵌入版本号)
- [**4. C 语言项目中的 SemVer 规则**](#4. C 语言项目中的 SemVer 规则)
- - [**4.1 头文件中定义版本号**](#4.1 头文件中定义版本号)
  - [**4.2 预发布和构建版本**](#4.2 预发布和构建版本)
- [**5. SemVer 在嵌入式项目中的实际应用**](#5. SemVer 在嵌入式项目中的实际应用)
- [**6. 总结**](#6. 总结)
- [7. 结束语](#7. 结束语)
- 相关文章：

1. SemVer 版本号格式

标准的 SemVer 2.0.0 规则如下：

复制代码

MAJOR.MINOR.PATCH

其中：

MAJOR（主版本号）：不兼容的 API 变更（重大架构调整、硬件不兼容）
MINOR（次版本号）：向后兼容的新功能（增加新特性、优化性能）
PATCH（补丁版本号）：向后兼容的 Bug 修复（修复错误、不影响接口）

🔹 示例

版本号	说明
`1.0.0`	第一个正式版本
`1.1.0`	增加了新功能（如支持 I2C 通讯）
`1.1.1`	修复了 I2C 传输 Bug
`2.0.0`	重大更新，不兼容旧 API（如改用 SPI 代替 I2C）

2. 嵌入式中的扩展规则

2.1 额外的构建号（Build Metadata）

嵌入式项目中，除了 MAJOR.MINOR.PATCH，可能还需要额外信息，比如：

复制代码

MAJOR.MINOR.PATCH.BUILD

BUILD（构建号） ：内部编译版本，用于区分同一个版本的不同构建
- 在 CI/CD 自动化构建时加上 Git 提交 ID 或时间戳 ，如：
  复制代码
```
1.2.3+20240314
1.2.3+commitabc123
```
- 用于调试、回溯固件版本，不影响 SemVer 兼容性

🔹 示例

版本号	说明
`1.2.3+4567`	版本 `1.2.3`，构建号 `4567`
`1.2.3+abc1234`	版本 `1.2.3`，Git 提交 ID `abc1234`

2.2 预发布版本（Pre-release）

嵌入式开发中可能有 Alpha/Beta 版本 ，可使用 SemVer 预发布标签：

复制代码

MAJOR.MINOR.PATCH-PRERELEASE

Alpha（-alpha）：早期测试版，可能有大量 Bug
Beta（-beta）：稳定性提高，但仍在测试
RC（-rc）：接近最终发布的候选版本

🔹 示例

版本号	说明
`1.0.0-alpha.1`	第一个 Alpha 版本
`1.0.0-beta.2`	第二个 Beta 版本
`1.0.0-rc.3`	第三个 Release Candidate 版本

2.3 特殊版本（修订号）

一些嵌入式项目可能会额外加 修订号（REVISION），用于区分硬件兼容性：

复制代码

MAJOR.MINOR.PATCH.REVISION

用于不同的硬件版本（PCB 版本）
例如：
复制代码
```
1.2.3.001  # 适用于 PCB v1.0
1.2.3.002  # 适用于 PCB v1.1
```
用于 Bootloader 和固件的匹配
复制代码
```
Bootloader: 1.0.0
Firmware:   1.2.3.001
```

3. 在 Git / CI/CD 中应用 SemVer

3.1 Git 标签（Git Tag）

Git 版本管理中，一般使用 git tag 进行版本标记：

bash 复制代码

git tag v1.2.3
git push origin v1.2.3

或带 预发布标签：

bash 复制代码

git tag v1.2.3-beta.1
git push origin v1.2.3-beta.1

3.2 GitHub Actions / GitLab CI 结合 SemVer

在 CI/CD 自动化构建时，可自动生成版本：

获取最新 Tag
bash 复制代码
```
git describe --tags --always
```

基于 git rev-list 计算 BUILD 号

bash 复制代码

BUILD_NUM=$(git rev-list --count HEAD)
echo "1.2.3+$BUILD_NUM"

示例：

bash 复制代码

Firmware Version: 1.2.3+4578

3.3 在固件中嵌入版本号

嵌入式系统可在代码中定义版本号，方便调试：

c 复制代码

#define FIRMWARE_VERSION "1.2.3"
#define BUILD_NUMBER     "4567"

printf("Firmware: %s (Build %s)\n", FIRMWARE_VERSION, BUILD_NUMBER);

4. C 语言项目中的 SemVer 规则

C 语言项目需要管理 库版本 、头文件，常用方式如下：

4.1 头文件中定义版本号

在 version.h 头文件中定义：

c 复制代码

#ifndef VERSION_H
#define VERSION_H

#define PROJECT_NAME "MyEmbeddedApp"
#define VERSION_MAJOR 1
#define VERSION_MINOR 2
#define VERSION_PATCH 3
#define VERSION_STRING "1.2.3"

#endif // VERSION_H

然后在 main.c 中使用：

c 复制代码

#include <stdio.h>
#include "version.h"

int main() {
    printf("Project: %s\n", PROJECT_NAME);
    printf("Version: %d.%d.%d\n", VERSION_MAJOR, VERSION_MINOR, VERSION_PATCH);
    return 0;
}

💡 作用：程序运行时可以打印版本信息，方便排查问题。

4.2 预发布和构建版本

SemVer 允许：

预发布版本：1.2.3-alpha.1
自动构建号：1.2.3+4567

在 version.h 里增加：

c 复制代码

#define VERSION_PRERELEASE "alpha.1"
#define BUILD_NUMBER "4578"

然后在 main.c 里：

c 复制代码

#ifdef VERSION_PRERELEASE
    printf("Pre-release: %s\n", VERSION_PRERELEASE);
#endif
#ifdef BUILD_NUMBER
    printf("Build: %s\n", BUILD_NUMBER);
#endif

💡 作用：区分开发版和正式版。

5. SemVer 在嵌入式项目中的实际应用

应用场景	示例版本号	说明
正式发布	`1.0.0`	适用于所有设备
增加新功能	`1.1.0`	增加 USB 支持
修复 Bug	`1.1.1`	修复 I2C 传输问题
开发中（Beta）	`1.2.0-beta.3`	第三个 Beta 版本
硬件版本兼容	`2.0.0.002`	第二版 PCB
自动构建版本	`1.2.3+4578`	CI/CD 自动生成

6. 总结

✅ 标准 SemVer： MAJOR.MINOR.PATCH

✅ 嵌入式扩展： MAJOR.MINOR.PATCH.BUILD（构建号）

✅ 预发布版本： MAJOR.MINOR.PATCH-PRERELEASE（Alpha/Beta/RC）

✅ 硬件兼容版本： MAJOR.MINOR.PATCH.REVISION（区分 PCB 版本）

✅ Git / CI/CD 支持： git tag v1.2.3 + git describe

🔹 推荐做法：

正式版本 ：1.2.3
开发测试 ：1.2.3-beta.1
自动构建 ：1.2.3+4567
不同硬件兼容 ：1.2.3.001

💡 采用 SemVer 让嵌入式项目的版本管理更加清晰，提高开发效率！🚀

7. 结束语

本节内容已经全部介绍完毕，希望通过这篇文章，大家对 SemVer 有了更深入的理解和认识。

感谢各位的阅读和支持，如果觉得这篇文章对你有帮助，请不要吝惜你的点赞和评论 ，这对我们非常重要。再次感谢大家的关注和支持 ！点我关注❤️

指针的神秘探险：从入门到精通的奇幻之旅 !

【嵌入式】嵌入式系统中的 SemVer 版本控制方案

嵌入式系统中的 SemVer 版本控制方案

目录

1. SemVer 版本号格式

2. 嵌入式中的扩展规则

2.1 额外的构建号（Build Metadata）

2.2 预发布版本（Pre-release）

2.3 特殊版本（修订号）

3. 在 Git / CI/CD 中应用 SemVer

3.1 Git 标签（Git Tag）

3.2 GitHub Actions / GitLab CI 结合 SemVer

3.3 在固件中嵌入版本号

4. C 语言项目中的 SemVer 规则

4.1 头文件中定义版本号

4.2 预发布和构建版本

5. SemVer 在嵌入式项目中的实际应用

6. 总结

7. 结束语

相关文章：