หน้านี้ได้รับการแปลโดย Cloud Translation API

บันทึกประจำรุ่นของปลั๊กอิน 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.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 เวอร์ชัน 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

ปัญหา #400492927

โปรเจ็กต์ที่แยก: ข้อผิดพลาดในการซีเรียลไลซ์ DeclarativeSchemaModel

ปัญหา #327770434

คำขอ: สำหรับการเลิกใช้งาน zipAlignEnabled โปรดบอกเหตุผลที่เลิกใช้งานและสิ่งที่ควรใช้แทน

ปัญหา #406464766

[AGP 8.9.0+] BuiltinKotlinCompilation ที่แสดงต่อปลั๊กอินคอมไพเลอร์ Kotlin ทั้งหมด

ปัญหา #405419218

อัปเดตทรัพยากร Dependency ของ Kotlin เป็นเวอร์ชัน 2.1.20 เมื่อสร้าง AGP 8.11

ปัญหา #372269616

อย่าบังคับใช้ com.android.internal.version-check เมื่ออัปเดตการกระจาย Gradle

ปัญหา #294183018

สร้างไม่สำเร็จเมื่อไม่มีไฟล์ Proguard

Dexer (D8)

ปัญหา #418143856

การแยกส่วน AutoClosable ทำให้บิลด์ AGP จากภายใน Android Studio ทำงานไม่ได้

Lint

ปัญหา #343347272

กฎ Lint BuildListAdds ไม่ตรวจพบการใช้ตัวดำเนินการ fun plusAssign (+=) ใน buildList

ปัญหา #399428893

ใช้ UseSdkSuppress เพื่อป้องกันผลบวกลวงในโค้ดตัวช่วยทดสอบ

ปัญหา #398924424

เตือนความขัดแย้งที่อาจเกิดขึ้นระหว่างสมาชิกกับส่วนขยาย

ปัญหา #406935594

การตรวจพบที่ผิดพลาดสำหรับปัญหา Lint `MemberExtensionConflict` หากตัวรับฟังก์ชันส่วนขยายเป็น Null ได้

ปัญหา #405442664

ผลบวกลวงของการตรวจสอบ `WrongGradleMedthod`

ปัญหา #405654866

ผลบวกลวงของ SyntheticAccessor สำหรับการเรียกสมาชิกสังเคราะห์ของคลาสข้อมูล

ปัญหา #406739378

ข้อผิดพลาด TestMode.SUPPRESSIBLE สำหรับปัญหาที่รายงานในนิพจน์ที่ติดป้ายกำกับได้

ปัญหา #406991279

ปัญหา Lint ใหม่ของ MemberExtensionConflict ที่เริ่มใน AGP 8.11.0-alpha03 - วิธีแก้ไข

ปัญหา #409716542

การตรวจสอบ Lint ในไฟล์ "libs.versions.toml" แนะนำให้อัปเกรดเป็น AGP เวอร์ชันที่ไม่รองรับ

Shrinker (R8)

ปัญหา #402800800

สร้าง AAB ที่ลงชื่อแล้วไม่ได้หลังจากอัปเดตเป็น AGP 8.9.0

ปัญหา #418568424

R8 ขัดข้องกับ min-api 24 เมื่อประมวลผลโค้ด JavaFuzzer

ปลั๊กอิน Android Gradle 8.11.1

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