تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

ضبط الإصدار

يجمع نظام إنشاء Android موارد التطبيق والرمز المصدري ويحزمهما في حِزم APK أو حِزم Android App Bundle التي يمكنك اختبارها ونشرها وتوقيعها وتوزيعها.

في نظرة عامة على إنشاء Gradle وبنية إنشاء تطبيق Android، ناقشنا مفاهيم الإنشاء وبنية تطبيق Android. والآن، حان وقت ضبط إعدادات الإنشاء.

مسرد مصطلحات تصميم Android

يساعدك نظام Gradle والمكوّن الإضافي لنظام Gradle المتوافق مع Android في ضبط الجوانب التالية من عملية التصميم:

أنواع الإصدارات

تحدّد أنواع الإصدار خصائص معيّنة يستخدمها Gradle عند إنشاء تطبيقك وتعبئته. ويتم عادةً إعداد أنواع الإصدار لمراحل مختلفة من دورة حياة التطوير.

على سبيل المثال، يتيح نوع الإصدار المخصّص لتصحيح الأخطاء خيارات تصحيح الأخطاء ويوقّع التطبيق باستخدام مفتاح تصحيح الأخطاء، بينما قد يقلّل نوع إصدار التطبيق حجم تطبيقك ويشوّشه ويوقّعه باستخدام مفتاح إصدار للتوزيع.

يجب تحديد نوع إصدار واحد على الأقل لإنشاء تطبيقك، إذ ينشئ "استوديو Android" نوعَي الإصدارين التصحيحي والعادي تلقائيًا. لبدء تخصيص إعدادات التغليف لتطبيقك، تعرَّف على كيفية ضبط أنواع الإصدارات.

نُسخ المنتج

تمثّل نكهات المنتجات إصدارات مختلفة من تطبيقك يمكنك طرحها للمستخدمين، مثل الإصدارات المجانية والمدفوعة. يمكنك تخصيص نُسخ المنتج لاستخدام رموز وموارد مختلفة مع مشاركة وإعادة استخدام الأجزاء المشتركة بين جميع إصدارات تطبيقك. نُسخ المنتج اختيارية، ويجب إنشاؤها يدويًا. لبدء إنشاء إصدارات مختلفة من تطبيقك، تعرَّف على كيفية ضبط أنواع المنتجات.

إنشاء أشكال متغيرة

إنّ صيغة الإصدار هي منتج مشترك من نوع الإصدار ونكهة المنتج، وهي الإعداد الذي يستخدمه Gradle لإنشاء تطبيقك. وباستخدام صيغ الإصدار، يمكنك إنشاء إصدار تصحيح الأخطاء من نكهات منتجك أثناء التطوير وإصدارات موقعة من نكهات منتجك للتوزيع. على الرغم من أنّك لا تضبط إعدادات صيغ الإصدار مباشرةً، يمكنك ضبط إعدادات أنواع الإصدارات ونكهات المنتجات التي تتكوّن منها. يؤدي إنشاء أنواع إصدارات أو نكهات منتجات إضافية إلى إنشاء صيغ إصدارات إضافية أيضًا. لمعرفة كيفية إنشاء خيارات الإصدارات وإدارتها، يمكنك الاطّلاع على النظرة العامة حول إعداد خيارات الإصدارات.

إدخالات البيان

يمكنك تحديد قيم لبعض خصائص ملف البيان في إعدادات صيغة الإصدار. وتحلّ قيم الإنشاء هذه محل القيم الحالية في ملف البيان. ويكون ذلك مفيدًا إذا كنت تريد إنشاء عدة صيغ من تطبيقك بأسماء تطبيقات مختلفة أو إصدارات مختلفة من حزمة تطوير البرامج (SDK) كحد أدنى أو إصدارات مختلفة من حزمة تطوير البرامج (SDK) المستهدَفة. عند توفّر بيانات متعددة، تدمج أداة دمج البيانات إعدادات البيانات.

التبعيات

يدير نظام الإنشاء تبعيات المشروع من نظام الملفات على جهازك ومن المستودعات البعيدة. هذا يعني أنّه ليس عليك البحث عن حِزم ثنائية لعمليات التبعية وتنزيلها ونسخها يدويًا إلى دليل مشروعك. لمزيد من المعلومات، يُرجى الاطّلاع على إضافة تبعيات الإصدار.

التوقيع

يتيح لك نظام الإنشاء تحديد إعدادات التوقيع في إعدادات الإنشاء، ويمكنه توقيع تطبيقك تلقائيًا أثناء عملية الإنشاء. يوقّع نظام الإنشاء إصدار تصحيح الأخطاء باستخدام مفتاح وشهادة تلقائيين باستخدام بيانات اعتماد معروفة لتجنُّب طلب كلمة المرور في وقت الإنشاء. لا يوقّع نظام الإنشاء على إصدار التطبيق إلا إذا حدّدت بشكل صريح إعدادات التوقيع لهذا الإصدار. إذا لم يكن لديك مفتاح إصدار، يمكنك إنشاء مفتاح كما هو موضّح في مقالة توقيع تطبيقك. ويجب توقيع إصدارات التطبيق لتوزيعها من خلال معظم متاجر التطبيقات.

تخفيض حجم الرموز والموارد

يتيح لك نظام الإصدار تحديد ملف مختلف لقواعد ProGuard لكل صيغة إصدار. عند إنشاء تطبيقك، يطبّق نظام الإنشاء المجموعة المناسبة من القواعد لتقليل حجم الرموز والموارد باستخدام أدوات تقليل الحجم المضمّنة، مثل R8. يمكن أن يساعد تقليل حجم الرموز والموارد في تقليل حجم حِزم APK أو AAB.

إتاحة حِزم APK المتعدّدة

يتيح لك نظام الإصدار إنشاء حِزم APK مختلفة تلقائيًا، يحتوي كل منها على الرمز البرمجي والموارد اللازمة لكثافة شاشة أو واجهة ثنائية للتطبيق (ABI) معيّنة. لمزيد من المعلومات، يُرجى الاطّلاع على إنشاء حِزم APK متعددة. ومع ذلك، يُنصح بإصدار حزمة تطبيق واحدة بتنسيق AAB، لأنّها تتيح تقسيم التطبيق حسب اللغة بالإضافة إلى كثافة الشاشة وواجهة التطبيق الثنائية (ABI)، مع تجنُّب الحاجة إلى تحميل عناصر متعددة على Google Play. يجب أن تستخدم جميع التطبيقات الجديدة التي تم إرسالها بعد أغسطس 2021 حِزم AAB.

إصدارات Java في إصدارات Android

سواء كان رمز المصدر مكتوبًا بلغة Java أو Kotlin أو كليهما، هناك عدة أماكن يجب فيها اختيار إصدار JDK أو إصدار لغة Java لإنشاء تطبيقك. لمزيد من التفاصيل، يُرجى الاطّلاع على إصدارات Java في إصدارات Android.

ملفات إعدادات التصميم

يتطلّب إنشاء إعدادات مخصّصة للإنشاء إجراء تغييرات على ملف واحد أو أكثر من ملفات إعدادات الإنشاء. تستخدم هذه الملفات النصية العادية لغة خاصة بالنطاق (DSL) لوصف منطق الإصدار ومعالجته باستخدام نص Kotlin البرمجي، وهو أحد أشكال لغة Kotlin. يمكنك أيضًا استخدام Groovy، وهي لغة ديناميكية لآلة Java الافتراضية (JVM)، من أجل ضبط إعدادات عمليات الإنشاء.

للبدء في ضبط إعدادات الإصدار، لا تحتاج إلى معرفة نص Kotlin البرمجي أو Groovy، لأنّ إضافة Android Gradle توفّر معظم عناصر DSL التي تحتاج إليها. لمزيد من المعلومات حول DSL الخاص بالمكوّن الإضافي لنظام Gradle المتوافق مع Android، يُرجى الاطّلاع على مستندات مرجع DSL. تعتمد نصوص Kotlin البرمجية أيضًا على Gradle Kotlin DSL الأساسية.

عند بدء مشروع جديد، ينشئ Android Studio تلقائيًا بعضًا من هذه الملفات ويملأها استنادًا إلى الإعدادات التلقائية المناسبة. للحصول على نظرة عامة حول الملفات التي تم إنشاؤها، راجِع بنية إصدار Android.

ملف Gradle Wrapper

برنامج Gradle المغلّف (gradlew) هو تطبيق صغير مضمّن في الرمز المصدر، وهو يعمل على تنزيل Gradle وتشغيله. يؤدي ذلك إلى تنفيذ عمليات الإنشاء بشكل أكثر اتساقًا. ينزّل المطوّرون رمز مصدر التطبيق ويشغّلون gradlew. سيؤدي ذلك إلى تنزيل حزمة Gradle المطلوبة وتشغيل Gradle لإنشاء تطبيقك.

يحتوي الملف gradle/wrapper/gradle-wrapper.properties على السمة distributionUrl التي توضّح إصدار Gradle المستخدَم لتشغيل عملية الإنشاء.

distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
distributionUrl=https\://services.gradle.org/distributions/gradle-8.0-bin.zip
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists

ملف إعدادات Gradle

يقع الملف settings.gradle.kts (لغة Kotlin الخاصة بالنطاق) أو الملف settings.gradle (لغة Groovy الخاصة بالنطاق) في دليل المشروع الجذر. يحدد ملف الإعدادات هذا إعدادات المستودع على مستوى المشروع، ويُعلم Gradle الوحدات التي يجب تضمينها عند إنشاء تطبيقك. ويجب أن تحدد المشاريع المتعددة الوحدات كل وحدة يجب تضمينها في الإصدار النهائي.

في معظم المشاريع، يبدو الملف على النحو التالي تلقائيًا:

Kotlin

pluginManagement {

    /**
      * The pluginManagement.repositories block configures the
      * repositories Gradle uses to search or download the Gradle plugins and
      * their transitive dependencies. Gradle pre-configures support for remote
      * repositories such as JCenter, Maven Central, and Ivy. You can also use
      * local repositories or define your own remote repositories. Here we
      * define the Gradle Plugin Portal, Google's Maven repository,
      * and the Maven Central Repository as the repositories Gradle should use to look for its
      * dependencies.
      */

    repositories {
        gradlePluginPortal()
        google()
        mavenCentral()
    }
}
dependencyResolutionManagement {

    /**
      * The dependencyResolutionManagement.repositories
      * block is where you configure the repositories and dependencies used by
      * all modules in your project, such as libraries that you are using to
      * create your application. However, you should configure module-specific
      * dependencies in each module-level build.gradle file. For new projects,
      * Android Studio includes Google's Maven repository and the Maven Central
      * Repository by default, but it does not configure any dependencies (unless
      * you select a template that requires some).
      */

  repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
  repositories {
      google()
      mavenCentral()
  }
}
rootProject.name = "My Application"
include(":app")

Groovy

pluginManagement {

    /**
      * The pluginManagement.repositories block configures the
      * repositories Gradle uses to search or download the Gradle plugins and
      * their transitive dependencies. Gradle pre-configures support for remote
      * repositories such as JCenter, Maven Central, and Ivy. You can also use
      * local repositories or define your own remote repositories. Here we
      * define the Gradle Plugin Portal, Google's Maven repository,
      * and the Maven Central Repository as the repositories Gradle should use to look for its
      * dependencies.
      */

    repositories {
        gradlePluginPortal()
        google()
        mavenCentral()
    }
}
dependencyResolutionManagement {

    /**
      * The dependencyResolutionManagement.repositories
      * block is where you configure the repositories and dependencies used by
      * all modules in your project, such as libraries that you are using to
      * create your application. However, you should configure module-specific
      * dependencies in each module-level build.gradle file. For new projects,
      * Android Studio includes Google's Maven repository and the Maven Central
      * Repository by default, but it does not configure any dependencies (unless
      * you select a template that requires some).
      */

    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
}
rootProject.name = "My Application"
include ':app'

ملف الإنشاء ذو المستوى الأعلى

يقع ملف build.gradle.kts (لغة Kotlin الخاصة بالنطاق) أو ملف build.gradle (لغة Groovy الخاصة بالنطاق) من المستوى الأعلى في دليل المشروع الجذر. ويحدّد عادةً الإصدارات الشائعة من المكوّنات الإضافية التي تستخدمها الوحدات في مشروعك.

يوضّح نموذج الرمز البرمجي التالي الإعدادات التلقائية وعناصر DSL في نص برمجة الإصدار ذي المستوى الأعلى بعد إنشاء مشروع جديد:

Kotlin

plugins {

    /**
     * Use `apply false` in the top-level build.gradle file to add a Gradle
     * plugin as a build dependency but not apply it to the current (root)
     * project. Don't use `apply false` in sub-projects. For more information,
     * see Applying external plugins with same version to subprojects.
     */

    id("com.android.application") version "8.11.0" apply false
    id("com.android.library") version "8.11.0" apply false
    id("org.jetbrains.kotlin.android") version "2.1.20" apply false
}

Groovy

plugins {

    /**
     * Use `apply false` in the top-level build.gradle file to add a Gradle
     * plugin as a build dependency but not apply it to the current (root)
     * project. Don't use `apply false` in sub-projects. For more information,
     * see Applying external plugins with same version to subprojects.
     */

    id 'com.android.application' version '8.11.0' apply false
    id 'com.android.library' version '8.11.0' apply false
    id 'org.jetbrains.kotlin.android' version '2.1.20' apply false
}

/** * The first section in the build configuration applies the Android Gradle plugin * to this build and makes the android block available to specify * Android-specific build options. */ plugins { id("com.android.application") } /** * Locate (and possibly download) a JDK used to build your kotlin * source code. This also acts as a default for sourceCompatibility, * targetCompatibility and jvmTarget. Note that this does not affect which JDK * is used to run the Gradle build itself, and does not need to take into * account the JDK version required by Gradle plugins (such as the * Android Gradle Plugin) */ kotlin { jvmToolchain(11) } /** * The android block is where you configure all your Android-specific * build options. */ android { /** * The app's namespace. Used primarily to access app resources. */ namespace = "com.example.myapp" /** * compileSdk specifies the Android API level Gradle should use to * compile your app. This means your app can use the API features included in * this API level and lower. */ compileSdk = 33 /** * The defaultConfig block encapsulates default settings and entries for all * build variants and can override some attributes in main/AndroidManifest.xml * dynamically from the build system. You can configure product flavors to override * these values for different versions of your app. */ defaultConfig { // Uniquely identifies the package for publishing. applicationId = "com.example.myapp" // Defines the minimum API level required to run the app. minSdk = 21 // Specifies the API level used to test the app. targetSdk = 33 // Defines the version number of your app. versionCode = 1 // Defines a user-friendly version name for your app. versionName = "1.0" } /** * The buildTypes block is where you can configure multiple build types. * By default, the build system defines two build types: debug and release. The * debug build type is not explicitly shown in the default build configuration, * but it includes debugging tools and is signed with the debug key. The release * build type applies ProGuard settings and is not signed by default. */ buildTypes { /** * By default, Android Studio configures the release build type to enable code * shrinking, using minifyEnabled, and specifies the default ProGuard rules file. */ getByName("release") { isMinifyEnabled = true // Enables code shrinking for the release build type. proguardFiles( getDefaultProguardFile("proguard-android.txt"), "proguard-rules.pro" ) } } /** * The productFlavors block is where you can configure multiple product flavors. * This lets you create different versions of your app that can * override the defaultConfig block with their own settings. Product flavors * are optional, and the build system does not create them by default. * * This example creates a free and paid product flavor. Each product flavor * then specifies its own application ID, so that they can exist on the Google * Play Store or an Android device simultaneously. * * If you declare product flavors, you must also declare flavor dimensions * and assign each flavor to a flavor dimension. */ flavorDimensions += "tier" productFlavors { create("free") { dimension = "tier" applicationId = "com.example.myapp.free" } create("paid") { dimension = "tier" applicationId = "com.example.myapp.paid" } } /** * To override source and target compatibility (if different from the * toolchain JDK version), add the following. All of these * default to the same value as kotlin.jvmToolchain. If you're using the * same version for these values and kotlin.jvmToolchain, you can * remove these blocks. */ //compileOptions { // sourceCompatibility = JavaVersion.VERSION_11 // targetCompatibility = JavaVersion.VERSION_11 //} //kotlinOptions { // jvmTarget = "11" //} } /** * The dependencies block in the module-level build configuration file * specifies dependencies required to build only the module itself. * To learn more, go to Add build dependencies. */ dependencies { implementation(project(":lib")) implementation("androidx.appcompat:appcompat:1.7.1") implementation(fileTree(mapOf("dir" to "libs", "include" to listOf("*.jar")))) }

/** * The first line in the build configuration applies the Android Gradle plugin * to this build and makes the android block available to specify * Android-specific build options. */ plugins { id 'com.android.application' } /** * Locate (and possibly download) a JDK used to build your kotlin * source code. This also acts as a default for sourceCompatibility, * targetCompatibility and jvmTarget. Note that this does not affect which JDK * is used to run the Gradle build itself, and does not need to take into * account the JDK version required by Gradle plugins (such as the * Android Gradle Plugin) */ kotlin { jvmToolchain 11 } /** * The android block is where you configure all your Android-specific * build options. */ android { /** * The app's namespace. Used primarily to access app resources. */ namespace 'com.example.myapp' /** * compileSdk specifies the Android API level Gradle should use to * compile your app. This means your app can use the API features included in * this API level and lower. */ compileSdk 33 /** * The defaultConfig block encapsulates default settings and entries for all * build variants and can override some attributes in main/AndroidManifest.xml * dynamically from the build system. You can configure product flavors to override * these values for different versions of your app. */ defaultConfig { // Uniquely identifies the package for publishing. applicationId 'com.example.myapp' // Defines the minimum API level required to run the app. minSdk 21 // Specifies the API level used to test the app. targetSdk 33 // Defines the version number of your app. versionCode 1 // Defines a user-friendly version name for your app. versionName "1.0" } /** * The buildTypes block is where you can configure multiple build types. * By default, the build system defines two build types: debug and release. The * debug build type is not explicitly shown in the default build configuration, * but it includes debugging tools and is signed with the debug key. The release * build type applies ProGuard settings and is not signed by default. */ buildTypes { /** * By default, Android Studio configures the release build type to enable code * shrinking, using minifyEnabled, and specifies the default ProGuard rules file. */ release { minifyEnabled true // Enables code shrinking for the release build type. proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro' } } /** * The productFlavors block is where you can configure multiple product flavors. * This lets you create different versions of your app that can * override the defaultConfig block with their own settings. Product flavors * are optional, and the build system does not create them by default. * * This example creates a free and paid product flavor. Each product flavor * then specifies its own application ID, so that they can exist on the Google * Play Store or an Android device simultaneously. * * If you declare product flavors, you must also declare flavor dimensions * and assign each flavor to a flavor dimension. */ flavorDimensions "tier" productFlavors { free { dimension "tier" applicationId 'com.example.myapp.free' } paid { dimension "tier" applicationId 'com.example.myapp.paid' } } /** * To override source and target compatibility (if different from the * tool chain JDK version), add the following. All of these * default to the same value as kotlin.jvmToolchain. If you're using the * same version for these values and kotlin.jvmToolchain, you can * remove these blocks. */ //compileOptions { // sourceCompatibility JavaVersion.VERSION_11 // targetCompatibility JavaVersion.VERSION_11 //} //kotlinOptions { // jvmTarget = '11' //} } /** * The dependencies block in the module-level build configuration file * specifies dependencies required to build only the module itself. * To learn more, go to Add build dependencies. */ dependencies { implementation project(":lib") implementation 'androidx.appcompat:appcompat:1.7.1' implementation fileTree(dir: 'libs', include: ['*.jar']) }

كتالوجات الإصدارات

إذا كان الإصدار يتضمّن وحدات متعدّدة ذات تبعيات مشتركة، أو إذا كان لديك مشاريع مستقلة متعدّدة ذات تبعيات مشتركة، ننصحك باستخدام قائمة إصدارات أو قائمة مواد (BOM) لتحديد الإصدارات الشائعة.

أنظمة تصميم أخرى

يمكن إنشاء تطبيقات Android باستخدام Bazel، ولكن لا تتوفّر أي إرشادات رسمية حول ذلك. لا يتيح "استوديو Android" رسميًا استخدام مشاريع Bazel.

للتعرّف بشكل أفضل على القيود الحالية المفروضة على استخدام Bazel، يُرجى الاطّلاع على المشاكل المعروفة.

يخضع كل من المحتوى وعيّنات التعليمات البرمجية في هذه الصفحة للتراخيص الموضحّة في ترخيص استخدام المحتوى. إنّ Java وOpenJDK هما علامتان تجاريتان مسجَّلتان لشركة Oracle و/أو الشركات التابعة لها.

تاريخ التعديل الأخير: 2025-07-13 (حسب التوقيت العالمي المتفَّق عليه)

WeChat
متابعة مطوّري برامج Android على WeChat
X
متابعة AndroidDev@ على X
YouTube
يمكنك زيارة قناة Android Developers على YouTube.

ضبط الإصدار

مسرد مصطلحات تصميم Android

إصدارات Java في إصدارات Android

ملفات إعدادات التصميم

ملف Gradle Wrapper

ملف إعدادات Gradle

Kotlin

Groovy

ملف الإنشاء ذو المستوى الأعلى

Kotlin

Groovy

ملف الإنشاء على مستوى الوحدة

إعدادات حزمة تطوير البرامج (SDK) لنظام التشغيل Android

نموذج نص برمجي لإنشاء وحدة التطبيق

Kotlin

Groovy

ملفات خصائص Gradle

إعادة ربط NDK بمسار أقصر (نظام التشغيل Windows فقط)

مزامنة المشروع مع ملفات Gradle

مجموعات المستندات المصدر

كتالوجات الإصدارات

أنظمة تصميم أخرى