บันทึกประจำรุ่นของปลั๊กอิน Android Gradle 8.11

ที่เก็บ JCenter กลายเป็นแบบอ่านอย่างเดียวเมื่อวันที่ 31 มีนาคม 2021 ดูข้อมูลเพิ่มเติมได้ที่การอัปเดตบริการ JCenter

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

หน้านี้อธิบายวิธีอัปเดตเครื่องมือ 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 นั้น ตัวอย่างต่อไปนี้จะตั้งค่า ปลั๊กอินเป็นเวอร์ชัน 8.11.0 จากไฟล์ build.gradle.kts

Kotlin

plugins {
    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 {
    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
}

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

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

อัปเดต Gradle

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

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

เวอร์ชันปลั๊กอินเวอร์ชัน Gradle ขั้นต่ำที่จำเป็น
8.118.13
8.108.11.1
8.98.11.1
8.88.10.2
8.78.9
8.68.7
8.58.7
8.48.6
8.38.4
8.28.2
8.18.0
8.08.0

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

เวอร์ชันปลั๊กอินเวอร์ชัน Gradle ที่จำเป็น
7.47.5
7.37.4
7.27.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.45.4.1 ขึ้นไป
3.4.0 - 3.4.35.1.1 ขึ้นไป
3.3.0 - 3.3.34.10.1 ขึ้นไป
3.2.0 - 3.2.14.6 ขึ้นไป
3.1.0 ขึ้นไป4.4+
3.0.0 ขึ้นไป4.1 ขึ้นไป
2.3.0 ขึ้นไป3.3 ขึ้นไป
2.1.3 - 2.2.32.14.1 - 3.5
2.0.0 - 2.1.22.10 - 2.13
1.5.02.2.1 - 2.13
1.2.0 - 1.3.12.2.1 - 2.9
1.0.0 - 1.1.32.2.1 - 2.3

คุณระบุเวอร์ชัน Gradle ได้ในเมนูไฟล์ > โครงสร้างโปรเจ็กต์ > โปรเจ็กต์ ใน Android Studio หรืออัปเดตเวอร์ชัน Gradle โดยใช้บรรทัดคำสั่ง วิธีที่แนะนำคือการใช้เครื่องมือบรรทัดคำสั่ง Gradle Wrapper ซึ่งจะอัปเดตสคริปต์ gradlew ตัวอย่างต่อไปนี้ จะตั้งค่า Gradle เวอร์ชัน 8.13 โดยใช้ Gradle Wrapper โปรดทราบว่าคุณต้องเรียกใช้คำสั่งนี้2 ครั้งเพื่ออัปเกรดทั้ง Gradle และ Gradle Wrapper เอง (ดูข้อมูลเพิ่มเติมได้ที่ การอัปเกรด Gradle Wrapper)

gradle wrapper --gradle-version 8.13

อย่างไรก็ตาม การดำเนินการนี้อาจล้มเหลวในบางกรณี เช่น หากคุณเพิ่งอัปเดต AGP และ AGP ไม่เป็นไปตามข้อกำหนดของ Gradle เวอร์ชันปัจจุบันอีกต่อไป ในกรณีนี้ คุณต้องแก้ไขการอ้างอิงการกระจาย Gradle ในไฟล์ gradle/wrapper/gradle-wrapper.properties ตัวอย่างต่อไปนี้ ตั้งค่า Gradle เป็นเวอร์ชัน 8.13 ในไฟล์ gradle-wrapper.properties

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

ความเข้ากันได้ของปลั๊กอิน Android Gradle และ Android Studio

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

เวอร์ชัน Android Studio เวอร์ชัน AGP ที่จำเป็น
การอัปเดตฟีเจอร์ใหม่ของ 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
การอัปเดตฟีเจอร์ใหม่ของ Ladybug | 2024.2.2 3.2-8.8
Ladybug | 2024.2.1 3.2-8.7
การอัปเดตฟีเจอร์ใหม่ของโคอาลา | 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 | 1/3/2022 3.2-8.1
Flamingo | 2022.2.1 3.2-8.0

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

เวอร์ชัน Android Studio เวอร์ชัน AGP ที่จำเป็น
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.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

การเปลี่ยนแปลงการกำหนดเวอร์ชัน (พฤศจิกายน 2020)

เรากำลังอัปเดตการกำหนดหมายเลขเวอร์ชันสำหรับปลั๊กอิน Android Gradle (AGP) เพื่อให้สอดคล้องกับเครื่องมือบิลด์ Gradle พื้นฐานมากขึ้น

การเปลี่ยนแปลงที่สำคัญมีดังนี้

  • ตอนนี้ AGP จะใช้การกำหนดเวอร์ชันเชิงความหมาย และการเปลี่ยนแปลงที่ไม่รองรับเวอร์ชันก่อนหน้าจะ กำหนดเป้าหมายสำหรับการเผยแพร่เวอร์ชันหลัก

  • AGP จะมีเวอร์ชันหลัก 1 เวอร์ชันต่อปี ซึ่งสอดคล้องกับ การเปิดตัวเวอร์ชันหลักของ Gradle

  • การเปิดตัวหลังจาก AGP 4.2 จะเป็นเวอร์ชัน 7.0 และจะต้องมีการอัปเกรด เป็น Gradle เวอร์ชัน 7.x การเผยแพร่ AGP ทุกเวอร์ชันหลักจะต้องมีการอัปเกรดเวอร์ชันหลัก ในเครื่องมือ Gradle พื้นฐาน

  • เราจะเลิกใช้งาน API ล่วงหน้าประมาณ 1 ปี พร้อมกับเปิดตัวฟังก์ชันการทำงานทดแทนพร้อมกัน API ที่เลิกใช้งานแล้ว จะถูกนำออกในอีกประมาณ 1 ปีต่อมาในระหว่างการอัปเดต ครั้งสำคัญครั้งถัดไป

ความเข้ากันได้

ระดับ API สูงสุดที่ปลั๊กอิน Android Gradle 8.11 รองรับคือ API ระดับ 36 ข้อมูลอื่นๆ เกี่ยวกับความเข้ากันได้มีดังนี้

เวอร์ชันขั้นต่ำ เวอร์ชันเริ่มต้น หมายเหตุ
Gradle 8.13 8.13 ดูข้อมูลเพิ่มเติมได้ที่การอัปเดต Gradle
เครื่องมือสร้าง SDK 35.0.0 35.0.0 ติดตั้งหรือกำหนดค่าเครื่องมือสร้าง SDK
NDK ไม่มี 27.0.12077973 ติดตั้งหรือกำหนดค่า NDK เวอร์ชันอื่น
JDK 17 17 ดูข้อมูลเพิ่มเติมได้ที่การตั้งค่าเวอร์ชัน JDK

ปัญหาที่แก้ไขแล้ว

ปลั๊กอิน Android Gradle 8.11.0

ปัญหาที่แก้ไขแล้ว
ปลั๊กอิน Android Gradle
โปรเจ็กต์ที่แยก: ข้อผิดพลาดในการซีเรียลไลซ์ DeclarativeSchemaModel
คำขอ: สำหรับการเลิกใช้งาน zipAlignEnabled โปรดบอกเหตุผลที่เลิกใช้งานและสิ่งที่ควรใช้แทน
[AGP 8.9.0+] BuiltinKotlinCompilation ที่แสดงต่อปลั๊กอินคอมไพเลอร์ Kotlin ทั้งหมด
อัปเดตทรัพยากร Dependency ของ Kotlin เป็นเวอร์ชัน 2.1.20 เมื่อสร้าง AGP 8.11
อย่าบังคับใช้ com.android.internal.version-check เมื่ออัปเดตการกระจาย Gradle
สร้างไม่สำเร็จเมื่อไม่มีไฟล์ Proguard
Dexer (D8)
การแยกส่วน AutoClosable ทำให้บิลด์ AGP จากภายใน Android Studio ทำงานไม่ได้
Lint
กฎ Lint BuildListAdds ไม่ตรวจพบการใช้ตัวดำเนินการ fun plusAssign (+=) ใน buildList
ใช้ UseSdkSuppress เพื่อป้องกันผลบวกลวงในโค้ดตัวช่วยทดสอบ
เตือนความขัดแย้งที่อาจเกิดขึ้นระหว่างสมาชิกกับส่วนขยาย
การตรวจพบที่ผิดพลาดสำหรับปัญหา Lint `MemberExtensionConflict` หากตัวรับฟังก์ชันส่วนขยายเป็น Null ได้
ผลบวกลวงของการตรวจสอบ `WrongGradleMedthod`
ผลบวกลวงของ SyntheticAccessor สำหรับการเรียกสมาชิกสังเคราะห์ของคลาสข้อมูล
ข้อผิดพลาด TestMode.SUPPRESSIBLE สำหรับปัญหาที่รายงานในนิพจน์ที่ติดป้ายกำกับได้
ปัญหา Lint ใหม่ของ MemberExtensionConflict ที่เริ่มใน AGP 8.11.0-alpha03 - วิธีแก้ไข
การตรวจสอบ Lint ในไฟล์ "libs.versions.toml" แนะนำให้อัปเกรดเป็น AGP เวอร์ชันที่ไม่รองรับ
Shrinker (R8)
สร้าง AAB ที่ลงชื่อแล้วไม่ได้หลังจากอัปเดตเป็น AGP 8.9.0
R8 ขัดข้องกับ min-api 24 เมื่อประมวลผลโค้ด JavaFuzzer