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

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 را در هر commit به شاخه انتشار حذف می‌کند.

ابزارهای محبوب خودکارسازی

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 را خودکار می‌کنند — این یکی از دلایل رایج خطاها در انتشار است.

همیشه Build Number را در هر بیلد افزایش دهید، حتی اگر Version Name تغییر نکند — این کار عملکرد صحیح مکانیسم به‌روزرسانی در فروشگاه‌های اپلیکیشن را تضمین می‌کند.

بهترین روش‌ها برای Build Number

versionCode را از 1 شروع کرده و برای هر بیلد 1 افزایش دهید. برای iOS از رویکرد مشابه با CFBundleVersion استفاده کنید. از اعداد ترکیبی در صورت عدم نیاز شدید خودداری کنید — عدد ترتیبی ساده راحت‌تر پیگیری می‌شود.

Build Number را با شماره بیلد سیستم CI/CD مرتبط کنید — این کار ردیابی از خطا تا commit خاص را ساده می‌کند. 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 تعبیه شده است.

# افزایش شماره بیلد به میزان ۱
xcrun agvtool next-version -all

# تنظیم شماره بیلد مشخص
xcrun agvtool new-version -all "3.0.1"

پرچم -all نسخه را در تمام targetهای پروژه به‌روز می‌کند که همگام‌سازی مقادیر بین اپلیکیشن اصلی و افزونه‌ها را تضمین می‌کند.

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 را پشتیبانی می‌کند.