מידע על Android Gradle Plugin

מערכת ה-build של Android Studio מבוססת על Gradle, והפלאגין של Android Gradle מוסיף כמה תכונות שספציפיות ל-build של אפליקציות Android.

בדף הזה מוסבר איך לשמור על עדכניות של כלי Gradle. הערות על פלאגין של Android Gradle זמינות בדף הערות הגרסה.

סיכום כללי של שינויים משמעותיים שצפויים בפלאגין של Android Gradle מופיע במפת הדרכים של הפלאגין של Android Gradle.

פרטים על הגדרת Android builds באמצעות Gradle מופיעים בדפים הבאים:

מידע נוסף על מערכת ה-build של Gradle זמין במדריך למשתמש של Gradle.

עדכון של הפלאגין של Android Gradle

כשמעדכנים את Android Studio, יכול להיות שתופיע הנחיה לעדכן באופן אוטומטי את הפלאגין Android Gradle לגרסה העדכנית ביותר שזמינה. אתם יכולים לאשר את העדכון או לציין גרסה באופן ידני בהתאם לדרישות הבנייה של הפרויקט.

אפשר לציין את גרסת הפלאגין בתפריט File > Project Structure > Project (קובץ > מבנה הפרויקט > פרויקט) ב-Android Studio, או בקובץ build.gradle.kts ברמה העליונה. גרסת הפלאגין חלה על כל המודולים שנבנו בפרויקט Android Studio הזה. בדוגמה הבאה, הפלאגין מוגדר לגרסה 9.0 מתוך הקובץ build.gradle.kts:

Kotlin

plugins {
    id("com.android.application") version "9.0" apply false
    id("com.android.library") version "9.0" apply false
    id("org.jetbrains.kotlin.android") version "2.2.21" apply false
}

Groovy

plugins {
    id 'com.android.application' version '9.0' apply false
    id 'com.android.library' version '9.0' apply false
    id 'org.jetbrains.kotlin.android' version '2.2.21' apply false
}

זהירות: אין להשתמש בתלות דינמית במספרי גרסאות, כמו 'com.android.tools.build:gradle:9.+'. השימוש בתכונה הזו עלול לגרום לעדכוני גרסה לא צפויים ולקושי בפתרון הבדלים בין גרסאות.

אם גרסת הפלאגין שצוינה לא הורדה, Gradle יוריד אותה בפעם הבאה שתבנו את הפרויקט או שתלחצו על File (קובץ) > Sync Project with Gradle Files (סנכרון הפרויקט עם קובצי Gradle) מסרגל התפריטים של Android Studio.

עדכון Gradle

כשמעדכנים את Android Studio, יכול להיות שתופיע הנחיה לעדכן גם את Gradle לגרסה העדכנית ביותר שזמינה. אתם יכולים לאשר את העדכון או לציין גרסה באופן ידני בהתאם לדרישות הבנייה של הפרויקט.

בטבלה הבאה מפורטת הגרסה של Gradle שנדרשת לכל גרסה של פלאגין Android ל-Gradle. כדי לקבל את הביצועים הטובים ביותר, מומלץ להשתמש בגרסה העדכנית ביותר של Gradle ושל הפלאגין.

גרסת הפלאגיןהגרסה המינימלית הנדרשת של Gradle
9.09.1.0
8.138.13
8.128.13
8.118.13
8.108.11.1
8.98.11.1
8.8‫8.10.2
8.78.9
8.68.7
8.58.7
8.48.6
8.38.4
8.28.2
8.1‫8.0
‫8.0‫8.0

גרסאות ישנות יותר

גרסת הפלאגיןגרסת Gradle הנדרשת
7.47.5
‫7.37.4
7.2‫7.3.3
‫7.17.2
7.07.0
‫4.2.0 ומעלה6.7.1
‫4.1.0 ומעלה‫6.5 ומעלה
‫4.0.0 ומעלה‫6.1.1 ואילך
‫3.6.0 - 3.6.45.6.4 ומעלה
‫3.5.0 - 3.5.4‫5.4.1 ומעלה
‫3.4.0 - 3.4.3‫5.1.1 ומעלה
‫3.3.0 - 3.3.3‫4.10.1 ומעלה
‫3.2.0 - 3.2.1‫4.6 ומעלה
3.1.0 ואילך‫4.4 ומעלה
‫3.0.0 ומעלה‫4.1 ומעלה
‫2.3.0 ומעלה‫3.3 ומעלה
‫2.1.3 עד 2.2.3‫2.14.1 עד 3.5
‫2.0.0 - 2.1.2‫2.10 - 2.13
1.5.0‫2.2.1 - 2.13
‫1.2.0 - 1.3.1‫2.2.1 עד 2.9
‫1.0.0 עד 1.1.3‫2.2.1 עד 2.3

אפשר לציין את גרסת Gradle בתפריט File > ‏Project Structure > ‏Project (קובץ > מבנה הפרויקט > פרויקט) ב-Android Studio, או לעדכן את גרסת Gradle באמצעות שורת הפקודה. הדרך המומלצת היא להשתמש בכלי שורת הפקודה Gradle Wrapper, שמעדכן את סקריפטים של gradlew. בדוגמה הבאה, הגרסה של Gradle מוגדרת ל-9.1.0 באמצעות Gradle Wrapper. חשוב לדעת שצריך להריץ את הפקודה הזו פעמיים כדי לשדרג גם את Gradle וגם את Gradle Wrapper עצמו (מידע נוסף זמין במאמר בנושא שדרוג Gradle Wrapper). 

gradle wrapper --gradle-version 9.1.0

עם זאת, יכול להיות שהפעולה תיכשל במקרים מסוימים, למשל אם הרגע עדכנתם את AGP והוא כבר לא תואם לגרסת Gradle הנוכחית. במקרה כזה, צריך לערוך את ההפניה להפצת Gradle בקובץ gradle/wrapper/gradle-wrapper.properties. בדוגמה הבאה, הגרסה של Gradle מוגדרת ל-9.1.0 בקובץ gradle-wrapper.properties. 

...
distributionUrl = https\://services.gradle.org/distributions/gradle-9.1.0-bin.zip
...

תאימות של פלאגין Android Gradle ו-Android Studio

מערכת ה-build של Android Studio מבוססת על Gradle, והפלאגין של Android Gradle ‏ (AGP) מוסיף כמה תכונות שספציפיות ל-build של אפליקציות Android. בטבלה הבאה מפורטת הגרסה של AGP שנדרשת לכל גרסה של Android Studio.

גרסת Android Studio גרסת AGP נדרשת
‫Otter 3 Feature Drop | ‏ 2025.2.3 ‫4.0-9.0
‫Otter 2 Feature Drop | 2025.2.2 ‫4.0-8.13
Otter | 2025.2.1 ‫4.0-8.13
‫Narwhal 4 Feature Drop | ‏ 2025.1.4 ‫4.0-8.13
‫Narwhal 3 Feature Drop | 2025.1.3 ‫4.0-8.13
‫Narwhal Feature Drop | ‏ 2025.1.2 ‫4.0-8.12
Narwhal | 2025.1.1 ‫3.2-8.11
‫Meerkat Feature Drop‏ | 2024.3.2 ‫3.2-8.10
סוריקטה | 2024.3.1 ‫3.2-8.9

גרסאות ישנות יותר

גרסת Android Studio גרסת AGP נדרשת
Ladybug Feature Drop | 2024.2.2 ‫3.2-8.8
Ladybug | 2024.2.1 ‫3.2-8.7
Koala Feature Drop | 2024.1.2 ‫3.2-8.6
קואלה | 2024.1.1 ‫3.2-8.5
מדוזה | 2023.3.1 ‫3.2-8.4
Iguana | 2023.2.1 ‫3.2-8.3
Hedgehog | ‏ 2023.1.1 3.2-8.2
ג'ירפה | 2022.3.1 3.2-8.1
פלמינגו | 2022.2.1 ‫3.2-8.0
Electric Eel | 2022.1.1 ‫3.2-7.4
‫Dolphin | ‏ 2021.3.1 ‫3.2-7.3
Chipmunk | 2021.2.1 ‫3.2-7.2
‫Bumblebee | ‏ 2021.1.1 ‫3.2-7.1
‫Arctic Fox | ‏ 2020.3.1 ‫3.1-7.0

מידע על החידושים בפלאגין Android Gradle זמין בהערות על הגרסה של פלאגין Android Gradle.

גרסאות מינימליות של כלים לרמת API ב-Android

יש גרסאות מינימליות של Android Studio ו-AGP שתומכות ברמת API ספציפית. שימוש בגרסאות ישנות יותר של Android Studio או AGP מהגרסאות שנדרשות בקובץ targetSdk או compileSdk של הפרויקט עלול לגרום לבעיות בלתי צפויות. מומלץ להשתמש בגרסת הטרום-השקה העדכנית של Android Studio ו-AGP כדי לעבוד על פרויקטים שמיועדים לגרסאות טרום-השקה של מערכת ההפעלה Android. אפשר להתקין גרסאות Preview של Android Studio לצד גרסה יציבה.

אלה הגרסאות המינימליות של Android Studio ו-AGP:

רמת ממשק API: גרסת Android Studio מינימלית גרסת AGP מינימלית
36.1 ‫Narwhal 3 Feature Drop | 2025.1.3 ‫8.13.0
36.0 Meerkat | 2024.3.1 Patch 1 8.9.1
35 Koala Feature Drop | 2024.2.1 ‫8.6.0
34 Hedgehog | ‏ 2023.1.1 ‫8.1.1
33 פלמינגו | 2022.2.1 7.2