Build Number — mi ez, a paraméter jelentése és növelése

Mi az a Build Number

Build Number — egy egyedi egész szám azonosító, amelyet a mobilalkalmazás minden egyes build-jéhez hozzárendelnek. Az alkalmazásboltok ezt használják a verzió újdonságának meghatározására — minél nagyobb a szám, annál újabb a build.

Androidban ezt a paramétert versionCode-nak, iOS-ben CFBundleVersion-nek hívják. Mindkét paraméter kötelező a közzétételhez, és monoton növekednie kell minden új build-del.

A Google Play Console Help (2025) adatai szerint a versionCode minden APK-feltöltéskor ellenőrzésre kerül: ha a feltöltött build versionCode-ja kisebb vagy egyenlő a már közzétettnél, a Google Play hibával elutasítja a fájlt.

Használja a Build Number-t a build-ek belső nyomon követésére — kapcsolja a számot a verziókezelő rendszerben lévő commit hash-hez a problémás kiadás gyors azonosításához.

Miért van szükség a Build Number-re

Build Number megoldja az alkalmazás minden egyes elkészített verziójának egyedi azonosítását. Nélküle lehetetlen meghatározni, melyik build újabb, ha a Version Name nem változott.

Az alkalmazásboltok, mint a Google Play és az App Store, a Build Number-t használják a frissítések során felmerülő konfliktusok feloldására. Ha a felhasználó egy új verziót telepít a régi fölé, a rendszer összehasonlítja a Build Number-t, és csak nagyobb érték esetén kínál frissítést.

Ez a mechanika kritikus a frissítések helyes kézbesítéséhez: monoton növekvő Build Number nélkül a felhasználók az alkalmazás régi verzióján rekedhetnek.

A Build Number formátumai

Build Number lehet egyszerű sorszám (1, 2, 3...) vagy összetett, amely további információkat kódol. Az összetett számok gyakran tartalmazzák a build dátumát vagy a CI/CD rendszer build-számát.

Androidban a versionCode egy int típusú egész szám, maximális értéke — 2100000000. iOS-ben a CFBundleVersion egy három pontokkal elválasztott számból álló karakterlánc, mindegyik legfeljebb 255.

Az Apple Developer (2025) adatai szerint a CFBundleVersion legfeljebb 3 komponenst támogat, de az App Store ezeket egyetlen sorszámmá egyesíti a verziók összehasonlításához.

Build Number Androidon

Androidban a Build Number-t a versionCode paraméterrel állítják be a build.gradle fájlban. Ez egy egész szám, amelynek egyedinek kell lennie a Google Play-ben közzétett alkalmazás minden verziójához.

A paramétert az android.defaultConfig blokkon belül deklarálják, és minden új kiadással növekednie kell. A Google Play nem engedi olyan APK feltöltését, amelynek versionCode-ja már használatban volt ugyanazon alkalmazás másik verziójához.

A Google Play Developer API (2025) adatai szerint a versionCode maximális értéke 2100000000. Javasolt 1-től kezdeni és minden új build esetén 1-gyel növelni a korlát kimerülésének elkerülése érdekében.

Használjon összetett versionCode-ot, amely a verziószámot kódolja: Major * 1000000 + Minor * 1000 + Patch — ez leegyszerűsíti a szemantikus verzióra való leképezést.

A versionCode korlátai Androidban

versionCode szigorú korlátozásokkal rendelkezik: ez egy 32 bites előjeles egész szám, így a maximális érték 2100000000. A korlát kimerülésekor az alkalmazás nem frissíthető a Google Play-ben.

Az Android App Bundle esetében a versionCode-ot a base modulban is meg kell adni, és minden feature modulnak lehet saját versionCode-ja. A Google Play ezeket egyetlen ellenőrző rendszerbe egyesíti.

Ezt a korlátozást figyelembe kell venni a verziózási stratégia kiválasztásakor — a szám túl gyors növekedése hosszú távon problémákhoz vezethet.

Build Number iOS-en

iOS-en a Build Number-t a CFBundleVersion kulccsal állítják be az Info.plist fájlban. Az Androidtól eltérően ez a paraméter egy karakterlánc, de szintén növekednie kell minden új build-del.

A CFBundleVersion formátuma — egy-három pontokkal elválasztott szám. Minden szám nem haladhatja meg a 255-öt. Az App Store a karakterláncot számok sorozataként értelmezi az összehasonlításhoz: az 1.0.1 újabbnak számít, mint az 1.0.0.

Az Apple Developer Documentation (2025) adatai szerint az App Store Connect megköveteli a CFBundleVersion egyediségét minden feltöltött build esetében. Ha egy már használt számmal rendelkező build-et töltenek fel, a rendszer elutasítja.

Kezelje a CFBundleVersion-t agvtool vagy Xcode build szkriptek segítségével, hogy garantálja a szám monoton növekedését minden build-nél.

Integráció az Xcode Build Settings-szel

Xcode lehetővé teszi a CFBundleVersion kezelését a Build Settings beállításain keresztül. A „Current Project Version“ mező beállítja az alapértéket, a Build Phase szkriptek pedig automatikusan növelhetik.

CI/CD esetén használja a increment_build_number fastlane bővítményt, amely beolvassa az aktuális verziót az Info.plist-ből, és egy adott értékkel növeli. Ez garantálja minden build egyediségét.

Ez a megközelítés teljesen automatizálja a Build Number kezelését, és kiküszöböli az emberi hibákat a kiadás előkészítése során.

Build Number automatikus növelése

A Build Number automatikus növelése általános gyakorlat a modern CI/CD pipeline-okban. A build-szám kézi növelése hibákhoz és konfliktusokhoz vezet a közzététel során.

GitHub Actions, GitLab CI és Jenkins beépített változókat biztosítanak a build-számmal. Ezeket a változókat a Gradle vagy Xcode szkriptekben használják a Build Number automatikus behelyettesítésére.

A GitLab CI Documentation (2025) adatai szerint a CI_PIPELINE_IID változó minden pipeline-hoz egyedi számot garantál, ami ideális a Build Number-ként való használatra.

Állítsa be az automatikus növelést CI/CD szinten — ez kiküszöböli a Build Number kézi módosításának szükségességét minden egyes commit-nál a kiadási ágba.

Népszerű automatizálási eszközök

GitHub Actions támogatja a beépített run_number változót, amely automatikusan növekszik minden pipeline-futtatásnál. Az érték átadható a Gradle-nek a versionCode-on keresztül.

Jenkins a BUILD_NUMBER változót használja, amely a build minden szakaszában elérhető. Xcode projektek esetén a Jenkins ezzel a számmal futtatja az agvtool-t.

Válassza ki az eszközt, amely integrált a technológiai stackjébe a további konfiguráció minimalizálása érdekében.

Build Number és Version Name

Build Number és Version Name párként működnek: az első — a gépeknek, a második — az embereknek. A Build Number biztosítja a technikai egyediséget, a Version Name — a felhasználó számára érthető szemantikát.

Androidban ez a két paraméter független: a versionCode növekedhet a versionName megváltoztatása nélkül (például build hiba javításához). iOS-ben a CFBundleVersion szintén nem kapcsolódik a CFBundleShortVersionString-hez.

A Stack Overflow Developer Survey (2024) adatai szerint a csapatok 82%-a használ automatikus Build Number növelést, de csak 45% automatizálja a Version Name frissítését — ez a kiadások során előforduló hibák egyik gyakori oka.

Mindig növelje a Build Number-t minden build-nél, még akkor is, ha a Version Name nem változik — ez garantálja a frissítési mechanizmus helyes működését az alkalmazásboltokban.

Be vált gyakorlatok a Build Number-hez

Kezdje a versionCode-ot 1-től, és növelje 1-gyel minden build esetén. iOS-ben használjon analóg megközelítést a CFBundleVersion-nel. Kerülje az összetett számokat, ha nincs szigorú szükség rá — az egyszerű sorszám könnyebben nyomon követhető.

Kapcsolja a Build Number-t a CI/CD rendszer build-számához — ez leegyszerűsíti a hibától az adott commit-ig történő visszakövetést. A Git tag a build-számmal és verzióval a legjobb gyakorlat a kiadások ellenőrzéséhez.

Build Number beállítási példák

Kódpéldák bemutatják, hogyan állítható be a Build Number automatikus növelése mindkét platformon.

versionCode Gradle-ben CI változóval

Androidban a versionCode beállítható egy CI/CD környezeti változón keresztül. Ha a változó nincs beállítva, az alapértelmezett érték kerül használatra.

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

versionCode a CI/CD változóból kapja az értéket, ami garantálja a szám egyediségét minden build esetén a pipeline-ban.

CFBundleVersion növelése agvtool segítségével

iOS-ben a Build Number automatikus növeléséhez az agvtool-t használják, amely az Xcode Command Line Tools része.

# Build szám növelése 1-gyel
xcrun agvtool next-version -all

# Konkrét build szám beállítása
xcrun agvtool new-version -all "3.0.1"

A -all zászló frissíti a verziót a projekt összes targetjében, ami garantálja az értékek szinkronizálását a fő alkalmazás és a bővítmények között.

Fastlane automatizáláshoz

Fastlane — népszerű eszköz a mobilalkalmazás-build-ek automatizálására. Az increment_build_number bővítmény automatikusan növeli a Build Number-t.

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

Fastlane integrálható bármely CI/CD rendszerrel, és támogatja mind az Android, mind az iOS projekteket.