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

ที่เก็บ 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.7.0 จากไฟล์ build.gradle.kts

Kotlin

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

Groovy

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

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

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

อัปเดต Gradle

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

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

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

gradle wrapper --gradle-version 8.7

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

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

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

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

เวอร์ชัน Android Studio เวอร์ชัน AGP ที่จําเป็น
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 ขั้นต่ำ
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.6 รองรับคือ API ระดับ 34 ข้อมูลอื่นๆ เกี่ยวกับความเข้ากันได้มีดังนี้

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

การเปลี่ยนแปลงลักษณะการทํางานของ Lint

ตั้งแต่ปลั๊กอิน Android Gradle 8.7.0-alpha08 เป็นต้นไป หากมี LintError เมื่อใช้ Lint โดยใช้ Gradle งานการวิเคราะห์ Lint จะแสดงข้อยกเว้น การเปลี่ยนแปลงนี้จะช่วยป้องกันไม่ให้แคชข้อผิดพลาดที่พบได้น้อยในแคชของบิลด์

แต่การเปลี่ยนแปลงนี้จะทำให้บิลด์ของโปรเจ็กต์ที่มีอินสแตนซ์ LintError จริงในไฟล์พื้นฐานของ Lint ใช้งานไม่ได้ ข้อความแสดงข้อผิดพลาดจะมีข้อมูลเกี่ยวกับการตรวจสอบ Lint ที่ทำให้เกิดปัญหา ในบางกรณี การอัปเดตไลบรารีที่เกี่ยวข้องอาจช่วยแก้ปัญหาได้ หากไม่ คุณก็ปิดใช้การตรวจสอบ Lint ที่มีปัญหาได้จนกว่าผู้เขียนไลบรารีจะแก้ไข

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

ปลั๊กอิน Android Gradle 8.7.0

ปัญหาที่แก้ไขแล้ว
ปลั๊กอิน Android Gradle
AGP ควรระบุว่ารองรับ API 35 ที่กำลังจะเปิดตัว
AGP 8.5: ระบบเรียกใช้งาน "mergeDebugResources" จำนวนมากขึ้น ซึ่งทำให้การสร้างช้าลง
ตั้งค่า ndk 27 เป็น NDK เริ่มต้นใน AGP
AGP ควรระบุว่ารองรับ API 35 ที่กำลังจะเปิดตัว
AGP ควรระบุว่ารองรับ API 35 ที่กำลังจะเปิดตัว
การเรียกใช้ Android Lint ล้มเหลวด้วย NoSuchFileException
BuildType#initWith คัดลอกบล็อกการประมวลผลผลลัพธ์ แต่ไม่ได้ใช้การกำหนดค่า ProGuard
ผสานแท็ก foregroundServiceType ไม่ได้
การเรียกใช้ Android Lint ล้มเหลวด้วย NoSuchFileException
Lint
Lint ควรตรวจสอบออบเจ็กต์ที่ไม่ถูกต้องซึ่งใช้เป็น ViewGroup
"ไม่มี android:host" สำหรับ URI ที่มีโฮสต์เป็นค่า Null
KtAnalysisSessionProvider ไม่เข้ากันได้กับการตรวจสอบ Lint ที่เปิดตัวใน 8.7.0-alpha04
"False positive" WrongConstant เมื่อใช้ PackageManager.ResolveInfoFlags.of กับ Kotlin

ปลั๊กอิน Android Gradle 8.7.1

ปัญหาที่แก้ไขแล้ว
ปลั๊กอิน Android Gradle
เอกสาร agp มี TBD จำนวนมาก
Lint
AGP 8.6.1: การถดถอย - การตรวจหาค่าคงที่ที่ไม่ถูกต้องของ Lint ไม่ผ่านเมื่อใช้ [Int].toLong() ภายใน @LongDef ใน Kotlin
ข้อผิดพลาดเกี่ยวกับ Lint "ต้องระบุโฮสต์อย่างน้อย 1 รายการ" เมื่อตั้งค่ารูปแบบ Intent Filter ของ http หรือ https

ปลั๊กอิน Android Gradle 8.7.2

ปัญหาที่แก้ไขแล้ว
Lint
AGP 8.7.0 - Lint False Positive RestrictedApi on NavOptionsBuilder.popUpTo
Shrinker (R8)
[R8 8.6.27] แทนที่การใช้งานเมธอดด้วย "throw null"
ไฟล์ ProGuard เริ่มต้นของ Android จะแสดงคำเตือนเมื่อใช้กับ R8 เวอร์ชันปัจจุบัน
MissingStartupProfileItemsDiagnostic ทำให้ไคลเอ็นต์ Gradle ขัดข้องด้วยข้อผิดพลาดหน่วยความจำไม่เพียงพอหากข้อความมีขนาดใหญ่เกินไป