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

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

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

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

หากต้องการดูสิ่งที่ได้รับการแก้ไขในปลั๊กอิน Android Gradle เวอร์ชันนี้ โปรดดูปัญหาที่ปิดแล้ว

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

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

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

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

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

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

KotlinGroovy
plugins {
    id("com.android.application") version "8.9.0" apply false
    id("com.android.library") version "8.9.0" apply false
    id("org.jetbrains.kotlin.android") version "2.1.10" apply false
}
 
plugins {
    id 'com.android.application' version '8.9.0' apply false
    id 'com.android.library' version '8.9.0' apply false
    id 'org.jetbrains.kotlin.android' version '2.1.10' apply false
}

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

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

อัปเดต Gradle

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

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

เวอร์ชันปลั๊กอินเวอร์ชัน Gradle ขั้นต่ำที่ต้องการ
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
7.47.5
เวอร์ชันปลั๊กอินเวอร์ชัน Gradle ที่จําเป็น
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.9 โดยใช้ Gradle Wrapper โปรดทราบว่าคุณต้องเรียกใช้คําสั่งนี้2 ครั้งเพื่ออัปเกรดทั้ง Gradle และ Gradle Wrapper เอง (ดูข้อมูลเพิ่มเติมได้ที่การอัปเกรด Gradle Wrapper) 

gradle wrapper --gradle-version 8.9

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

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

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

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

เวอร์ชัน Android Studio เวอร์ชัน AGP ที่จําเป็น
Meerkat | 2024.3.1 3.2-8.9
การอัปเดตฟีเจอร์ 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
Hedgehog | 2023.1.1 3.2-8.2
Giraffe | 2022.3.1 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 ขั้นต่ำ
Baklava Preview Meerkat | 2024.3.1 8.9.0
35 การอัปเดตฟีเจอร์ Koala | 2024.2.1 8.6.0
34 Hedgehog | 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 สูงสุดที่พลิแกน Gradle ของ Android เวอร์ชัน 8.9 รองรับคือ API ระดับ 35 ข้อมูลอื่นๆ เกี่ยวกับความเข้ากันได้มีดังนี้

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

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

ปลั๊กอิน Android Gradle 8.9.0

ปัญหาที่แก้ไขแล้ว
ปลั๊กอิน Android Gradle
แสดงข้อความแสดงข้อผิดพลาดที่นําไปใช้ได้เมื่องานการตั้งค่า GMD ไม่สําเร็จเนื่องจากมีพื้นที่ในดิสก์ไม่เพียงพอ
ปลั๊กอิน com.android.settings ไม่รู้จัก targetSdk
ข้อผิดพลาดที่ไม่เป็นประโยชน์ "ไม่ได้ระบุ compileSdkVersion โปรดเพิ่มลงใน build.gradle"
ไม่มี "Clean build" ในเมนู "Build"
โปรดอนุญาตให้ Kotlin ในตัวของ AGP เพิ่มการพึ่งพา kotlin stdlib โดยอัตโนมัติ
อัปเดต shouldConfigureKotlinPlatformAttribute เพื่อจัดการการรองรับ Kotlin ในตัว
ระบุไวยากรณ์ Kotlin ของ Gradle ในข้อความแสดงข้อผิดพลาดสําหรับ `checkTestedAppObfuscationRelease`
ข้อผิดพลาดเกี่ยวกับคลัง Fused เมื่อสามารถปรับปรุงการพึ่งพาที่ยังไม่ได้รับการแก้ไข
ระบบจะไม่ส่งพร็อพเพอร์ตี้ระบบจาก gradle.properties ไปยัง R8 Gradle Workers ในกระบวนการแยกต่างหาก
กำหนด BuiltArtifact.outputFile เป็นประเภทไฟล์
การไม่ระบุเนมสเปซในไลบรารีที่ผสานจะแสดงข้อความแสดงข้อผิดพลาดที่ไม่ชัดเจน
ตัวเลือก lint ใน AGP 7.1.0-alpha08 ไม่อนุญาตให้ใช้ stdout
ปลั๊กอิน Android Gradle: ตัวแปรควรแสดงชื่อชุดแหล่งที่มา
แคชการกําหนดค่ามีความเปราะบางต่อการตั้งค่าตัวแปรสภาพแวดล้อม TERM
AndroidComponentsExtension.addSourceSetConfigurations ใช้งานไม่ได้เมื่อเปิดใช้สถิติ
สคริปต์เริ่มต้น "C:\Users\mypc\AppData\Local\Temp\ijresolvers2.gradle" บรรทัดที่ 162
AndroidComponentsExtension.addSourceSetConfigurations ใช้งานไม่ได้เมื่อเปิดใช้สถิติ
Dexer (D8)
java.lang.VerifyError: Verifier rejected class: [0x430] copy1 v2<-v264 type=Undefined cat=3
Lint
Lint ขัดข้องเมื่อใช้การตรวจสอบ Lint ของ Gradle
Lint ดำเนินการไม่สำเร็จด้วย InstantiationException โดยไม่มีข้อความข้อยกเว้นในสแต็กเทรซของ Lint
การตรวจหาของ Lint ที่ให้ผลบวกลวง android.permission.SCHEDULE_EXACT_ALARM มีการอนุญาตให้แอประบบเท่านั้น
ควรใช้การตรวจสอบ StringFormatInvalid กับเมธอด Compose stringResource
คำอธิบายประกอบ RequiresFeature ใช้กับไฟล์ Kotlin ไม่ได้
kotlin android.os.Handler removeCallbacks Runnable
WrongConstant lint ในคําจํากัดความแทนที่จะเป็นการใช้ค่าคงที่โดยใช้ shift
WrongConstant lint ปรากฏ 2 ครั้ง
ข้อยกเว้นรันไทม์ต่ำกว่า API 26 ที่มี Java nio API ที่ไม่รองรับ (ไม่มีข้อผิดพลาดเกี่ยวกับ Lint)
Lint ป้องกันไม่ให้ใช้ RequiresApi แม้แต่ในเมธอดตัวช่วยส่วนตัวในทดสอบ
โหมด K2 แสดงคำเตือน RestrictedApi เมื่อใช้ .hasRoute(Route::class) ใน Android Studio
Lint แนะนำให้แทนที่ @RequiresExtension ใน test ด้วย @SdkSuppress ซึ่งไม่รองรับส่วนขยาย SDK
Lint รายงานเลย์เอาต์ที่ฝังไว้โดยไม่จำเป็นอย่างไม่ถูกต้องเมื่อ FrameLayout ใช้กับ fitSystemWindows เพื่อตัด RelativeLayout ย่อยที่ต้องใช้การกรอกข้อความที่กำหนดเอง
กฎ CoarseFineLocation ของ Lint ไม่คำนึงถึงแอตทริบิวต์ maxSdkVersion
AppLinkSplitToWebAndCustom is UnknownIssue in lint 8.7.3
การตรวจสอบ Lint ทำให้ StringEscapeDetector ขัดข้องใน "\\ "
คำเตือน lint ไม่ถูกต้องสำหรับคำอธิบายประกอบ `@Parcelize` ในอินเทอร์เฟซที่ปิด
AS 2024.3.1.4 ค้างเป็นพักๆ เมื่อแก้ไขข้อความ Kotlin
การผสานรวม Lint
lintVitalRelease จะไม่ทำงานโดยอัตโนมัติเมื่อสร้าง App Bundle
Shrinker (R8)
Gson Proguard ไม่ทํางานอย่างถูกต้องหลังจากอัปเกรดเป็น AGP 8.8
java.lang.VerifyError: Verifier rejected class
Leanback ขัดข้องเมื่อมีการย่อขนาดด้วย R8 ที่รวมอยู่ใน AGP 8.10.0-alpha04