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 أيضًا في الوحدة الأساسية، وكل وحدة ميزة يمكن أن يكون لها 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، الذي يزداد تلقائيًا مع كل تشغيل لخط الإنتاج. يمكن تمرير القيمة إلى 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 — هذا يضمن العمل الصحيح لآلية التحديث في متاجر التطبيقات.

أفضل الممارسات لـ Build Number

ابدأ versionCode من 1 وزد بـ 1 لكل بناء. لـ iOS استخدم نهجًا مماثلًا مع CFBundleVersion. تجنب الأرقام المركبة إلا إذا كانت ضرورية بشدة — الرقم المتسلسل البسيط أسهل في التتبع.

اربط Build Number برقم بناء نظام CI/CD — هذا يبسّط التعقب من الخطأ إلى commit محدد. علامة Git مع رقم البناء والإصدار هي أفضل ممارسة لإدارة الإصدارات.

أمثلة تكوين 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 يتم استخدام agvtool، المضمن في Xcode Command Line Tools، للزيادة التلقائية لـ Build Number.

# زيادة رقم البناء بـ 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 على حد سواء.