Build Number — 定义、参数含义与递增

什么是 Build Number

Build Number — 是分配给每个移动应用构建的唯一整型标识符。应用商店使用它来确定版本的新旧程度 — 数字越大，构建越新。

在 Android 中，此参数称为 versionCode，在 iOS 中称为 CFBundleVersion。这两个参数都是发布的必需项，并且必须随着每个新构建单调递增。

根据 Google Play Console Help (2025) 的数据，每次上传 APK 时都会检查 versionCode：如果上传的构建的 versionCode 小于或等于已发布的版本，Google Play 会拒绝该文件并报错。

使用 Build Number 进行内部构建跟踪 — 将编号与版本控制系统中的提交哈希关联，以快速识别有问题的版本。

为什么需要 Build Number

Build Number 解决了应用程序每个构建版本的唯一标识问题。如果没有它，当 Version Name 未更改时，无法确定哪个构建更新.

像 Google Play 和 App Store 这样的应用商店使用 Build Number 来解决更新时的冲突。如果用户在旧版本之上安装新版本，系统会比较 Build Number，并且仅在值更大时提供更新。

这种机制对于正确交付更新至关重要：没有单调递增的 Build Number，用户可能会停留在应用程序的旧版本上。

Build Number 的格式

Build Number 可以是简单的顺序号 (1, 2, 3...) 或编码附加信息的复合号。复合数字通常包含构建日期或 CI/CD 系统的构建编号。

对于 Android，versionCode 是 int 类型的整数，最大值为 2100000000。对于 iOS，CFBundleVersion 是由点分隔的三个数字组成的字符串，每个数字不超过 255。

根据 Apple Developer (2025) 的数据，CFBundleVersion 最多支持 3 个组件，但 App Store 将它们作为单个序号用于版本比较。

Android 中的 Build Number

在 Android 中，Build Number 通过 build.gradle 文件中的 versionCode 参数设置。这是一个必须对 Google Play 中发布的每个应用程序版本唯一的整数。

该参数在 android.defaultConfig 块内声明，并且必须随着每个新版本递增。Google Play 不允许上传 versionCode 已用于同一应用程序其他版本的 APK。

根据 Google Play Developer API (2025) 的数据，versionCode 的最大值为 2100000000。建议从 1 开始，每次新构建增加 1，以避免达到限制。

使用编码版本号的复合 versionCode：Major * 1000000 + Minor * 1000 + Patch — 这简化了到语义版本的映射。

Android 中 versionCode 的限制

versionCode 有严格的限制：它是一个 32 位有符号整数，因此最大值为 2100000000。当达到限制时，应用程序将无法在 Google Play 中更新。

对于 Android App Bundle，versionCode 也在基础模块中指定，每个功能模块可以有自己独立的 versionCode。Google Play 将它们合并到一个统一的验证系统中。

在选择版本策略时，必须考虑此限制 — 数字增长过快可能导致长期问题。

iOS 中的 Build Number

在 iOS 中，Build Number 通过 Info.plist 文件中的 CFBundleVersion 键设置。与 Android 不同，此参数是一个字符串，但也必须随着每个新构建递增。

CFBundleVersion 的格式 — 一到三个由点分隔的数字。每个数字不得超过 255。App Store 将字符串解释为用于比较的数字序列：1.0.1 被认为比 1.0.0 更新。

根据 Apple Developer Documentation (2025) 的数据，App Store Connect 要求每个上传的构建的 CFBundleVersion 是唯一的。如果上传的构建使用了已经用过的编号，系统将拒绝它。

通过 agvtool 或 Xcode 构建脚本管理 CFBundleVersion，以确保每次构建编号单调递增。

与 Xcode Build Settings 的集成

Xcode 允许通过 Build Settings 管理 CFBundleVersion。“Current Project Version” 字段设置基础值，Build Phase 脚本可以自动增加它。

对于 CI/CD，使用 fastlane 插件 increment_build_number，它从 Info.plist 读取当前版本并增加指定值。这保证了每个构建的唯一性。

这种方法完全自动化了 Build Number 的管理，并消除了准备发布时的人为错误。

Build Number 的自动递增

Build Number 的自动递增 是现代 CI/CD 流水线中的标准做法。手动增加构建编号会导致发布时的错误和冲突。

GitHub Actions、GitLab CI 和 Jenkins 提供带有构建编号的内置变量。这些变量在 Gradle 或 Xcode 脚本中用于自动替换 Build Number。

根据 GitLab CI Documentation (2025) 的数据，CI_PIPELINE_IID 变量为每个流水线保证唯一的编号，非常适合用作 Build Number。

在 CI/CD 级别配置自动递增 — 这将消除每次提交到发布分支时手动更改 Build Number 的需要。

流行的自动化工具

GitHub Actions 支持内置变量 run_number，它会为每次流水线执行自动递增。该值可以通过 versionCode 传递给 Gradle。

Jenkins 使用 BUILD_NUMBER 变量，该变量在构建的所有阶段可用。对于 Xcode 项目，Jenkins 使用此编号运行 agvtool。

选择与您的技术栈集成的工具，以最大限度地减少额外配置。

Build Number 和 Version Name

Build Number 和 Version Name 作为一对工作：前者 — 用于机器，后者 — 用于人类。Build Number 提供技术唯一性，Version Name — 提供用户可理解的语义。

在 Android 中，这两个参数是独立的：versionCode 可以在不更改 versionName 的情况下递增（例如，修复构建错误）。在 iOS 中，CFBundleVersion 也不依赖于 CFBundleShortVersionString。

根据 Stack Overflow Developer Survey (2024) 的数据，82% 的团队使用 Build Number 的自动递增，但只有 45% 自动更新 Version Name — 这是发布时常见错误的原因之一。

即使 Version Name 没有更改，也要在每次构建时增加 Build Number — 这可确保应用商店中更新机制的正确运行。

Build Number 的最佳实践

从 1 开始 versionCode，每次构建增加 1。对于 iOS，使用与 CFBundleVersion 类似的方法。如果没有严格需要，避免使用复合编号 — 简单的顺序号更容易跟踪。

将 Build Number 与 CI/CD 系统的构建编号关联 — 这简化了从错误到特定提交的跟踪。带有构建编号和版本的 Git 标签是控制发布的最佳实践。

Build Number 配置示例

代码示例 展示了如何配置两个平台上 Build Number 的自动递增。

在 Gradle 中使用 CI 变量的 versionCode

在 Android 中，可以通过 CI/CD 环境变量设置 versionCode。如果变量未设置，则使用默认值。

android {
    defaultConfig {
        versionCode System.getenv("CI_PIPELINE_ID")?.toInteger() ?: 1
        versionName "1.2.0"
    }
}

versionCode 从 CI/CD 变量获取值，这保证了流水线中每次构建编号的唯一性。

通过 agvtool 递增 CFBundleVersion

在 iOS 中，使用 agvtool 自动增加 Build Number，该工具内置于 Xcode Command Line Tools 中。

# 将构建编号增加 1
xcrun agvtool next-version -all

# 设置特定的构建编号
xcrun agvtool new-version -all "3.0.1"

-all 标志 更新项目所有目标中的版本，这保证了主应用程序和扩展之间的值同步。

Fastlane 实现自动化

Fastlane — 用于自动化移动应用构建的流行工具。increment_build_number 插件自动增加 Build Number。

increment_build_number(
    build_number: ENV["BUILD_NUMBER"] ||
                 latest_testflight_build_number + 1
)

Fastlane 可集成到任何 CI/CD 系统，并支持 Android 和 iOS 项目。