เกี่ยวกับปลั๊กอิน Android Gradle

ระบบบิลด์ของ Android Studio อิงตาม Gradle และปลั๊กอิน Android Gradle จะเพิ่มฟีเจอร์หลายอย่างที่เฉพาะเจาะจงสำหรับการบิลด์แอป Android

หน้านี้อธิบายวิธีอัปเดตเครื่องมือ Gradle ให้เป็นเวอร์ชันล่าสุดอยู่เสมอ ดูบันทึกประจำรุ่น เกี่ยวกับปลั๊กอิน Android Gradle ได้ที่หน้าบันทึกประจำรุ่น

ดูสรุปภาพรวมของการเปลี่ยนแปลงที่ไม่รองรับเวอร์ชันเดิมที่กำลังจะเกิดขึ้นในปลั๊กอิน Android Gradle ได้ที่แผนงานปลั๊กอิน Android Gradle

ดูรายละเอียดวิธีกำหนดค่าบิลด์ Android ด้วย Gradle ได้ที่หน้าต่อไปนี้

ดูข้อมูลเพิ่มเติมเกี่ยวกับระบบบิลด์ Gradle ได้ที่ คู่มือผู้ใช้ Gradle

อัปเดตปลั๊กอิน Android Gradle

เมื่ออัปเดต Android Studio คุณอาจได้รับข้อความแจ้งให้อัปเดตปลั๊กอิน Android Gradle เป็นเวอร์ชันล่าสุดที่มีอยู่โดยอัตโนมัติ คุณเลือกที่จะยอมรับการอัปเดตหรือระบุเวอร์ชันด้วยตนเองตามข้อกำหนดในการสร้างโปรเจ็กต์ได้

คุณระบุเวอร์ชันปลั๊กอินได้ใน เมนูไฟล์ > โครงสร้าง โปรเจ็กต์ > โปรเจ็กต์ใน 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
}

ข้อควรระวัง: คุณไม่ควรใช้ทรัพยากร Dependency แบบไดนามิกในหมายเลขเวอร์ชัน เช่น 'com.android.tools.build:gradle:9.+' การใช้ฟีเจอร์นี้อาจทำให้เกิดการอัปเดตเวอร์ชันที่ไม่คาดคิดและทำให้แก้ไขความแตกต่างของเวอร์ชันได้ยาก

หากยังไม่ได้ดาวน์โหลดปลั๊กอินเวอร์ชันที่ระบุ Gradle จะดาวน์โหลดปลั๊กอิน ในครั้งถัดไปที่คุณสร้างโปรเจ็กต์หรือคลิก File > Sync Project with Gradle Files จากแถบเมนูของ Android Studio

อัปเดต Gradle

เมื่ออัปเดต Android Studio คุณอาจได้รับข้อความแจ้งให้อัปเดต Gradle เป็นเวอร์ชันล่าสุดที่มีด้วย คุณเลือกที่จะยอมรับการอัปเดตหรือระบุเวอร์ชันด้วยตนเองตามข้อกำหนดในการสร้างโปรเจ็กต์ได้

ตารางต่อไปนี้แสดงเวอร์ชัน Gradle ที่จำเป็นสำหรับปลั๊กอิน Android Gradle แต่ละเวอร์ชัน คุณควรใช้ Gradle และปลั๊กอินทั้ง 2 รายการในเวอร์ชันล่าสุดเท่าที่จะเป็นไปได้เพื่อประสิทธิภาพการทำงานที่ดีที่สุด

เวอร์ชันปลั๊กอิน	เวอร์ชัน Gradle ขั้นต่ำที่จำเป็น
9.0	9.1.0
8.13	8.13
8.12	8.13
8.11	8.13
8.10	8.11.1
8.9	8.11.1
8.8	8.10.2
8.7	8.9
8.6	8.7
8.5	8.7
8.4	8.6
8.3	8.4
8.2	8.2
8.1	8.0
8.0	8.0

เวอร์ชันเก่ากว่า

เวอร์ชันปลั๊กอิน	เวอร์ชัน Gradle ที่จำเป็น
7.4	7.5
7.3	7.4
7.2	7.3.3
7.1	7.2
7.0	7.0
4.2.0 ขึ้นไป	6.7.1
4.1.0 ขึ้นไป	6.5 ขึ้นไป
4.0.0 ขึ้นไป	6.1.1 ขึ้นไป
3.6.0 - 3.6.4	5.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 ได้ในเมนูไฟล์ > โครงสร้างโปรเจ็กต์ > โปรเจ็กต์ใน Android Studio หรืออัปเดตเวอร์ชัน Gradle โดยใช้บรรทัดคำสั่ง วิธีที่แนะนำคือการใช้เครื่องมือบรรทัดคำสั่ง Gradle Wrapper ซึ่งจะอัปเดตสคริปต์ gradlew ตัวอย่างต่อไปนี้ จะตั้งค่า Gradle เวอร์ชัน 9.1.0 โดยใช้ Gradle Wrapper โปรดทราบว่าคุณต้องเรียกใช้คำสั่งนี้2 ครั้งเพื่ออัปเกรดทั้ง Gradle และ Gradle Wrapper เอง (ดูข้อมูลเพิ่มเติมได้ที่ การอัปเกรด Gradle Wrapper)

gradle wrapper --gradle-version 9.1.0

อย่างไรก็ตาม การดำเนินการนี้อาจล้มเหลวในบางกรณี เช่น หากคุณเพิ่งอัปเดต AGP และ 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

ระบบบิลด์ของ Android Studio ใช้ Gradle และปลั๊กอิน Android Gradle (AGP) จะเพิ่มฟีเจอร์หลายอย่างที่เฉพาะเจาะจงสำหรับการสร้างแอป Android ตารางต่อไปนี้แสดง AGP เวอร์ชันที่จำเป็นสำหรับ Android Studio แต่ละเวอร์ชัน

เวอร์ชัน Android Studio	เวอร์ชัน AGP ที่จำเป็น
การเปิดตัวฟีเจอร์ Otter 3 \| 2025.2.3	4.0-9.0
การอัปเดตฟีเจอร์ใหม่ของ Otter 2 \| 2025.2.2	4.0-8.13
Otter \| 2025.2.1	4.0-8.13
การเปิดตัวฟีเจอร์ Narwhal 4 \| 2025.1.4	4.0-8.13
การเปิดตัวฟีเจอร์ Narwhal 3 \| 2025.1.3	4.0-8.13
การเปิดตัวฟีเจอร์ Narwhal \| 2025.1.2	4.0-8.12
Narwhal \| 2025.1.1	3.2-8.11
การอัปเดตฟีเจอร์ใหม่ของ Meerkat \| 2024.3.2	3.2-8.10
Meerkat \| 1/3/2024	3.2-8.9

เวอร์ชันเก่ากว่า

เวอร์ชัน Android Studio	เวอร์ชัน AGP ที่จำเป็น
การอัปเดตฟีเจอร์ใหม่ของ Ladybug \| 2024.2.2	3.2-8.8
Ladybug \| 2024.2.1	3.2-8.7
การอัปเดตฟีเจอร์ใหม่ของ Koala \| 2024.1.2	3.2-8.6
Koala \| 2024.1.1	3.2-8.5
Jellyfish \| 2023.3.1	3.2-8.4
Iguana \| 2023.2.1	3.2-8.3
เม่น \| 2023.1.1	3.2-8.2
Giraffe \| 2022.3.1	3.2-8.1
Flamingo \| 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 เวอร์ชันตัวอย่าง คุณติดตั้ง Android Studio เวอร์ชันตัวอย่างควบคู่กับเวอร์ชันเสถียรได้

เวอร์ชันขั้นต่ำของ Android Studio และ AGP มีดังนี้

ระดับ API	เวอร์ชัน Android Studio ขั้นต่ำ	เวอร์ชัน AGP ขั้นต่ำ
36.1	การเปิดตัวฟีเจอร์ Narwhal 3 \| 2025.1.3	8.13.0
36.0	Meerkat \| 2024.3.1 แพตช์ 1	8.9.1
35	การอัปเดตฟีเจอร์ใหม่ของ Koala \| 2024.2.1	8.6.0
34	เม่น \| 2023.1.1	8.1.1
33	Flamingo \| 2022.2.1	7.2