Build Number — что это, значение параметра и инкремент

Что такое Build Number

Build Number — это уникальный целочисленный идентификатор, который присваивается каждой сборке мобильного приложения. Магазины приложений используют его для определения новизны версии — чем больше число, тем новее сборка.

В Android этот параметр называется versionCode, в iOS — CFBundleVersion. Оба параметра являются обязательными для публикации и должны монотонно возрастать с каждым новым билдом.

По данным Google Play Console Help (2025), versionCode проверяется при каждой загрузке APK: если загружается сборка с versionCode меньше или равным уже опубликованной, Google Play отклоняет файл с ошибкой.

Используйте Build Number для внутреннего трекинга сборок — связывайте номер с commit hash в системе контроля версий для быстрой идентификации проблемного релиза.

Зачем нужен 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 использует их как единый порядковый номер для сравнения версий.

Build Number на Android

На Android Build Number задаётся параметром versionCode в файле build.gradle. Это целое число, которое должно быть уникальным для каждой версии приложения, публикуемой в Google Play.

Параметр объявляется внутри блока android.defaultConfig и должен увеличиваться с каждым новым релизом. Google Play не позволяет загрузить APK с versionCode, который уже был использован для другой версии того же приложения.

По данным Google Play Developer API (2025), максимальное значение versionCode — 2100000000. Рекомендуется начинать с 1 и увеличивать на 1 для каждой новой сборки, чтобы избежать исчерпания лимита.

Используйте составной versionCode, кодирующий номер версии: Major * 1000000 + Minor * 1000 + Patch — это упрощает сопоставление с семантической версией.

Ограничения versionCode в Android

versionCode имеет строгие ограничения: это 32-битное целое число со знаком, поэтому максимальное значение — 2100000000. При исчерпании лимита приложение нельзя будет обновить в Google Play.

Для Android App Bundle versionCode также указывается в модуле base, а для каждого модуля feature может быть свой versionCode. Google Play объединяет их в единую систему проверки.

Это ограничение важно учитывать при выборе стратегии версионирования — слишком быстрый рост числа может привести к проблемам в долгосрочной перспективе.

Build Number на iOS

На iOS Build Number задаётся ключом CFBundleVersion в файле Info.plist. В отличие от Android, этот параметр является строкой, но также должен увеличиваться с каждой новой сборкой.

Формат CFBundleVersion — от одного до трёх чисел, разделённых точками. Каждое число не может превышать 255. App Store интерпретирует строку как последовательность чисел для сравнения: 1.0.1 считается новее, чем 1.0.0.

По данным Apple Developer Documentation (2025), App Store Connect требует уникальности CFBundleVersion для каждой загруженной сборки. Если загрузить билд с уже использованным номером, система отклонит его.

Управляйте CFBundleVersion через agvtool или скрипты сборки Xcode, чтобы гарантировать монотонный рост номера при каждой сборке.

Интеграция с Xcode Build Settings

Xcode позволяет управлять CFBundleVersion через настройки Build Settings. Поле «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, которая автоматически увеличивается для каждого запуска пайплайна. Значение можно передавать в Gradle через versionCode.

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 — это одна из частых причин ошибок при релизе.

Всегда увеличивайте Build Number при каждой сборке, даже если Version Name не меняется — это гарантирует корректную работу механизма обновлений в магазинах приложений.

Best Practices для Build Number

Начинайте versionCode с 1 и увеличивайте на 1 для каждой сборки. Для iOS используйте аналогичный подход с CFBundleVersion. Избегайте составных номеров, если нет строгой необходимости — простое последовательное число легче отслеживать.

Связывайте Build Number с номером билда CI/CD системы — это упрощает трассировку от ошибки до конкретного коммита. Git tag с номером сборки и версией — лучшая практика для контроля релизов.

Примеры настройки Build Number

Примеры кода показывают, как настроить автоматический инкремент Build Number на обеих платформах.

versionCode в Gradle с CI переменной

В Android versionCode можно задать через переменную окружения CI/CD. Если переменная не установлена, используется значение по умолчанию.

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

versionCode получает значение из переменной CI/CD, что гарантирует уникальность номера для каждой сборки в пайплайне.

Инкремент CFBundleVersion через agvtool

В iOS для автоматического увеличения Build Number используется agvtool, который встроен в 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 проекты.