构建号是什么
构建号是流水线平台自动维护的单调递增编号：GitLab 的 CI_PIPELINE_IID、GitHub 的 github.run_number、Jenkins 的 BUILD_NUMBER 都是同一类东西。它用来区分「同名版本的多次构建」，方便排序、追溯与问题定位。注意它只是顺序标识：不跨平台可比，也不携带语义，不应单独作为发布版本使用。
基本信息
| 适用平台 | GitLab CI、GitHub Actions、Jenkins 等流水线平台 |
|---|---|
| 平台变量 | GitLab $CI_PIPELINE_IID（项目内递增）；GitHub github.run_number；Jenkins $BUILD_NUMBER |
| 用途 | 构建产物命名、发布记录排序、问题定位、产物溯源 |
| 注意 | 不跨平台可比，仅用于同一系统内的顺序标识 |
典型使用场景
- 产物命名：app-1.8.0-build.42.tar.gz，同名版本之间可区分
- 问题定位：线上 version.txt 里的构建号对应到具体流水线与提交
- 排序追溯：发布记录按构建号排，比时间戳更可靠
- 版本组合：正式版本号 + 构建号（1.8.0+build.42）兼顾语义与顺序
- 排查重复发布：同名版本多次构建时，用它识别「到底发的哪一次」
- 本地与 CI 统一变量：脚本读同一个构建标识，CI 内由平台变量填充、本地回退占位值，避免两套写法
组合版本写法
组合版本写法
VERSION="1.8.0+build.${CI_PIPELINE_IID:-local}" # CI 内取平台编号，本地回退 local
echo "$VERSION" > dist/version.txt # 写进制品元数据，线上核版一查即明
# 镜像标签不要只用构建号：语义标签 + 构建号并存，发布记录更稳把构建号写进制品元数据（如 version.txt 或镜像注解），线上核对版本时一查即明，省去「翻 CI 界面反查」的时间。
构建号在不同平台的语义细节不同：GitLab 的 IID 是项目内可见编号，另有全局 id；GitHub 的 run_number 按工作流递增，重建同一提交也会继续增长，看到「编号不一致」属正常。
构建号只保证递增、不保证连续：失败重试、取消、跳过都会消耗编号，不能用相邻编号的差值推算任何数量。