บันทึกประจำรุ่นสำหรับตัวอย่างปลั๊กอิน Android Gradle

หน้านี้มีบันทึกประจำรุ่นสำหรับการเปิดตัว Android Gradle Plugin (AGP) เวอร์ชันตัวอย่าง

ปลั๊กอิน Android Gradle 9.0

ปลั๊กอิน Android Gradle 9.0 เป็นรุ่นหลักใหม่ของ AGP และมีการเปลี่ยนแปลง API และ ลักษณะการทำงาน

หากต้องการอัปเดตเป็นปลั๊กอิน Android Gradle 9.0.0-rc02 ให้ใช้ผู้ช่วยอัปเกรดปลั๊กอิน Android Gradle ใน Android Studio Panda | 2025.3.1

ผู้ช่วยการอัปเกรด AGP จะช่วยรักษาลักษณะการทำงานที่มีอยู่เมื่ออัปเกรดโปรเจ็กต์ในกรณีที่เหมาะสม ซึ่งจะช่วยให้คุณอัปเกรดโปรเจ็กต์เพื่อใช้ AGP 9.0 ได้ แม้ว่าคุณจะยังไม่พร้อมที่จะใช้ค่าเริ่มต้นใหม่ทั้งหมดใน AGP 9.0 ก็ตาม

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

ระดับ API ของ Android สูงสุดที่ปลั๊กอิน Android Gradle 9.0.0-rc02 รองรับคือ API ระดับ 36

ปลั๊กอิน Android Gradle 9.0.0-rc02 ต้องใช้ Gradle 9.0.0

android ตอนนี้คลาส DSL จะใช้เฉพาะอินเทอร์เฟซสาธารณะใหม่เท่านั้น

ในช่วงหลายปีที่ผ่านมา เราได้เปิดตัวอินเทอร์เฟซใหม่สำหรับ DSL และ API เพื่อให้ควบคุมได้ดียิ่งขึ้นว่า API ใดเป็นแบบสาธารณะ AGP เวอร์ชัน 7.x และ 8.x ยังคงใช้ประเภท DSL แบบเก่า (เช่น BaseExtension) ซึ่ง ยังได้ใช้การติดตั้งใช้งานอินเทอร์เฟซสาธารณะใหม่ด้วย เพื่อรักษาความเข้ากันได้ ขณะที่การทำงานในอินเทอร์เฟซดำเนินต่อไป

AGP 9.0 จะใช้อินเทอร์เฟซ DSL ใหม่ของเราเท่านั้น และการใช้งานได้เปลี่ยนไปเป็นประเภทใหม่ที่ซ่อนไว้อย่างสมบูรณ์ ซึ่ง ยังเป็นการนำสิทธิ์เข้าถึง API ของตัวแปรเก่าที่เลิกใช้งานแล้วออกด้วย

หากต้องการอัปเดตเป็น AGP 9.0 คุณอาจต้องดำเนินการต่อไปนี้

• ตรวจสอบว่าโปรเจ็กต์ของคุณใช้ได้กับ Kotlin ในตัว: ปลั๊กอิน org.jetbrains.kotlin.android ใช้ไม่ได้กับ DSL ใหม่

• เปลี่ยนโปรเจ็กต์ KMP ไปใช้ ปลั๊กอินไลบรารี Android Gradle สำหรับ KMP: การใช้ปลั๊กอิน org.jetbrains.kotlin.multiplatform ในโปรเจ็กต์ย่อย Gradle เดียวกันกับปลั๊กอิน com.android.library และ com.android.application ไม่สามารถใช้ร่วมกับ DSL ใหม่ได้

• อัปเดตไฟล์บิลด์: แม้ว่าการเปลี่ยนแปลงอินเทอร์เฟซจะมุ่งเน้นให้ DSL มีความคล้ายคลึงกันมากที่สุด แต่อาจมีการเปลี่ยนแปลงเล็กๆ น้อยๆ

• อัปเดตตรรกะการสร้างที่กำหนดเองเพื่ออ้างอิง DSL และ API ใหม่ แทนที่การอ้างอิง DSL ภายในด้วยอินเทอร์เฟซ DSL สาธารณะ โดยส่วนใหญ่แล้ว การแทนที่จะเป็นการแทนที่แบบ 1:1 แทนที่การใช้ applicationVariants และ API ที่คล้ายกันด้วย androidComponents API ใหม่ ซึ่งอาจซับซ้อนกว่าเนื่องจาก androidComponents API ได้รับการออกแบบมาให้มีความเสถียรมากขึ้นเพื่อให้ปลั๊กอินใช้งานร่วมกันได้นานขึ้น ดูตัวอย่างได้ที่ สูตร Gradle

• อัปเดตปลั๊กอินของบุคคลที่สาม: ปลั๊กอินของบุคคลที่สามบางรายการอาจยังคงต้องพึ่งพาอินเทอร์เฟซหรือ API ที่ ไม่ได้เปิดเผยอีกต่อไป ย้ายข้อมูลไปยังปลั๊กอินเวอร์ชันที่เข้ากันได้ กับ AGP 9.0

การเปลี่ยนไปใช้อินเทอร์เฟซ DSL ใหม่จะป้องกันไม่ให้ปลั๊กอินและสคริปต์บิลด์ Gradle ใช้ API ที่เลิกใช้งานแล้วต่างๆ ซึ่งรวมถึง

androidComponents {
    onVariants() { variant ->
        variant.signingConfig
            .enableV1Signing.set(false)
    }
}

androidComponents {
    beforeVariants(
        selector()
            .withBuildType("debug")
            .withFlavor("color", "blue")
    ) { variantBuilder ->
        variantBuilder.enable = false
    }
  }

หากอัปเดตเป็น AGP 9.0 และเห็นข้อความแสดงข้อผิดพลาดต่อไปนี้ แสดงว่า โปรเจ็กต์ของคุณยังอ้างอิงประเภทเก่าบางประเภทอยู่

java.lang.ClassCastException: class com.android.build.gradle.internal.dsl.ApplicationExtensionImpl$AgpDecorated_Decorated
cannot be cast to class com.android.build.gradle.BaseExtension

หากถูกปลั๊กอินของบุคคลที่สามที่ไม่รองรับบล็อก คุณสามารถเลือกไม่ใช้และ กลับไปใช้การติดตั้งใช้งานเก่าสำหรับ DSL รวมถึง API ตัวแปรเก่าได้ ในระหว่างนี้ คุณจะใช้ส่วนติดต่อใหม่ได้ด้วย และยังอัปเดตตรรกะการสร้างของคุณเองเป็น API ใหม่ได้ หากต้องการเลือกไม่ใช้ ให้ใส่บรรทัดนี้ในไฟล์ gradle.properties ของคุณ

android.newDsl=false

นอกจากนี้ คุณยังเริ่มอัปเกรดเป็น API ใหม่ก่อนที่จะอัปเกรดเป็น AGP 9.0 ได้ด้วย อินเทอร์เฟซใหม่มีอยู่ใน AGP หลายเวอร์ชัน คุณจึงใช้ทั้งเวอร์ชันใหม่และเวอร์ชันเก่าได้ เอกสารอ้างอิง AGP API แสดง API Surface สำหรับ AGP แต่ละเวอร์ชัน และเวลาที่เพิ่มแต่ละคลาส เมธอด และฟิลด์

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

หากพบว่า DSL หรือ Variant API ใหม่ไม่มีความสามารถหรือฟีเจอร์บางอย่าง โปรดรายงานปัญหาโดยเร็วที่สุด

Kotlin ในตัว

ปลั๊กอิน Android Gradle 9.0 เปิดตัวการรองรับ Kotlin ในตัวและเปิดใช้โดยค่าเริ่มต้น ซึ่งหมายความว่าคุณไม่จำเป็นต้องใช้ปลั๊กอิน org.jetbrains.kotlin.android (หรือ kotlin-android) ในไฟล์บิลด์อีกต่อไป เพื่อคอมไพล์ไฟล์ต้นฉบับ Kotlin ซึ่งจะช่วยลดความซับซ้อนของการผสานรวม Kotlin กับ AGP หลีกเลี่ยงการใช้ API ที่เลิกใช้งานแล้ว และปรับปรุงประสิทธิภาพในบางกรณี

ดังนั้น เมื่ออัปเกรดโปรเจ็กต์เป็น AGP 9.0 คุณจะต้องย้ายไปใช้ Kotlin ในตัวหรือเลือกไม่ใช้ด้วย

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

การขึ้นอยู่กับปลั๊กอิน Kotlin สำหรับ Gradle ในรันไทม์

ตอนนี้ปลั๊กอิน Android Gradle 9.0 มีทรัพยากร Dependency รันไทม์ในปลั๊กอิน Kotlin Gradle (KGP) 2.2.10 เพื่อให้การรองรับ Kotlin ในตัว ซึ่งหมายความว่าคุณไม่ต้องประกาศเวอร์ชัน KGP อีกต่อไป และหากใช้ KGP เวอร์ชันต่ำกว่า 2.2.10 Gradle จะอัปเกรดเวอร์ชัน KGP เป็น 2.2.10 โดยอัตโนมัติ ในทำนองเดียวกัน หากคุณใช้ KSP เวอร์ชันต่ำกว่า 2.2.10-2.0.2 AGP จะอัปเกรดเป็น 2.2.10-2.0.2 เพื่อให้ตรงกับ KGP เวอร์ชัน

อัปเกรดเป็น KGP เวอร์ชันที่สูงกว่า

หากต้องการใช้ KGP หรือ KSP เวอร์ชันที่สูงกว่า ให้เพิ่มข้อมูลต่อไปนี้ลงในไฟล์ build ระดับบนสุด

buildscript {
    dependencies {
        // For KGP
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:KGP_VERSION")

        // For KSP
        classpath("com.google.devtoolsksp:symbol-processing-gradle-plugin:KSP_VERSION")
    }
}

ดาวน์เกรดเป็น KGP เวอร์ชันที่ต่ำกว่า

คุณจะดาวน์เกรดเวอร์ชัน KGP ได้ก็ต่อเมื่อเลือกไม่ใช้ Kotlin ในตัว เนื่องจาก AGP 9.0 จะเปิดใช้ Kotlin ในตัวโดยค่าเริ่มต้น และ Kotlin ในตัว ต้องใช้ KGP 2.2.10 ขึ้นไป

หากต้องการใช้ KGP หรือ KSP เวอร์ชันที่ต่ำกว่า ให้ประกาศเวอร์ชันนั้นในไฟล์บิลด์ระดับบนสุดโดยใช้การประกาศเวอร์ชันที่แน่นอน ดังนี้

buildscript {
    dependencies {
        // For KGP
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin") {
            version { strictly("KGP_VERSION") }
        }

        // For KSP
        classpath("com.google.devtoolsksp:symbol-processing-gradle-plugin") {
            version { strictly("KSP_VERSION") }
        }
    }
}

โปรดทราบว่าเวอร์ชัน KGP ขั้นต่ำที่คุณดาวน์เกรดได้คือ 2.0.0

การรองรับ IDE สำหรับการตั้งค่าการทดสอบ

AGP 9.0 รองรับ IDE ของ Android Studio อย่างเต็มรูปแบบสำหรับ การทดสอบฟิกเจอร์

ปลั๊กอิน Fused Library

Fused Library Plugin (ตัวอย่าง) ช่วยให้คุณเผยแพร่ไลบรารีหลายรายการเป็น Android Library AAR เดียวได้ ซึ่งจะช่วยให้ผู้ใช้ พึ่งพาอาร์ติแฟกต์ที่คุณเผยแพร่ได้ง่ายขึ้น

ดูข้อมูลเกี่ยวกับการเริ่มต้นใช้งานได้ที่เผยแพร่ไลบรารี Android หลายรายการเป็นรายการเดียวด้วย Fused Library

การเปลี่ยนแปลงลักษณะการทำงาน

ปลั๊กอิน Android Gradle 9.0 มีลักษณะการทำงานใหม่ดังนี้

AGP 9.0 มีการอัปเดตค่าเริ่มต้นของพร็อพเพอร์ตี้ Gradle ต่อไปนี้ ซึ่งจะช่วยให้คุณเลือกที่จะคงลักษณะการทำงานของ AGP 8.13 ไว้เมื่ออัปเกรดได้

android {
  defaultConfig {
    testInstrumentationRunner = "..."
  }
}

android {
  buildFeatures {
    resValues = true
  }
}

android {
  buildFeatures {
    shaders = true
  }
}

ฟีเจอร์ที่นำออก

ปลั๊กอิน Android Gradle 9.0 จะนำฟังก์ชันการทำงานต่อไปนี้ออก

• การรองรับแอป Wear OS ที่ฝัง
  AGP 9.0 จะนำการรองรับการฝังแอป Wear OS ออก ซึ่ง Play ไม่รองรับอีกต่อไป ซึ่งรวมถึงการนำwearAppการกำหนดค่าและ AndroidSourceSet.wearAppConfigurationName DSL ออก ดูวิธีเผยแพร่แอปไปยัง Wear OS ได้ที่หัวข้อเผยแพร่ไปยัง Wear OS
• androidDependencies และsourceSetsรายงานงาน
• การรองรับ APK แยกของความหนาแน่น
  AGP 9.0 จะนำการรองรับการสร้าง APK แยกตามความหนาแน่นของหน้าจอออก เราได้นำฟังก์ชันการทำงานและ API ที่เกี่ยวข้องออกแล้ว หากต้องการแยก APK ตามความหนาแน่นของหน้าจอโดยใช้ AGP 9.0 ขึ้นไป ให้ใช้ App Bundle

DSL ที่เปลี่ยนแปลง

ปลั๊กอิน Android Gradle 9.0 มีการเปลี่ยนแปลง DSL ที่ส่งผลกับส่วนอื่นดังนี้

• นำการกำหนดพารามิเตอร์ของ CommonExtension ออกแล้ว

  การเปลี่ยนแปลงที่ทําให้เกิดข้อขัดข้องนี้เป็นเพียงการเปลี่ยนแปลงระดับแหล่งที่มาเพื่อช่วยหลีกเลี่ยงการเปลี่ยนแปลงที่ทําให้เกิดข้อขัดข้องระดับแหล่งที่มาในอนาคต แต่ก็หมายความว่าต้องย้ายเมธอดบล็อกจาก CommonExtension ไปยัง ApplicationExtension, LibraryExtension, DynamicFeatureExtension และ TestExtension

  เมื่ออัปเกรดโปรเจ็กต์เป็น AGP 9.0 ให้ปรับโครงสร้างโค้ดปลั๊กอิน Gradle ซึ่งใช้พารามิเตอร์หรือเมธอดบล็อกเหล่านั้น ตัวอย่างเช่น มีการอัปเดตปลั๊กอินต่อไปนี้ เพื่อนำพารามิเตอร์ประเภทออกและไม่ใช้ วิธีการบล็อกที่นำออกแล้ว

  AGP 8.13

  val commonExtension: CommonExtension<*, *, *, *, *, *> =
          extensions.getByType(CommonExtension::class)
  commonExtension.apply {
      defaultConfig {
          minSdk {
              version = release(28)
          }
      }
  }
  

  AGP 9.0

  val commonExtension: CommonExtension =
          extensions.getByType(CommonExtension::class)
  commonExtension.apply {
      defaultConfig.apply {
          minSdk {
              version = release(28)
          }
      }
  }
  

  สำหรับปลั๊กอินที่กำหนดเป้าหมายเป็น AGP เวอร์ชันต่างๆ การใช้ Getter โดยตรง จะเข้ากันได้แบบไบนารีกับ AGP เวอร์ชันที่ต่ำกว่า 9.0

นำ DSL ออกแล้ว

ปลั๊กอิน Android Gradle 9.0 จะนำสิ่งต่อไปนี้ออก

• AndroidSourceSet.jni เนื่องจากใช้งานไม่ได้

• AndroidSourceSet.wearAppConfigurationName เนื่องจากเกี่ยวข้องกับ การรองรับแอป Wear OS แบบฝังที่นำออกไปแล้ว

• BuildType.isRenderscriptDebuggable เนื่องจากใช้งานไม่ได้

• DependencyVariantSelection โดยจะแทนที่ด้วย DependencySelection ซึ่งแสดงเป็น kotlin.android.localDependencySelection

• Installation.installOptions(String) โดยจะแทนที่ด้วย พร็อพเพอร์ตี้ที่เปลี่ยนแปลงได้ของ Installation.installOptions

• บล็อก PostProcessing ที่อยู่ในขั้นทดลองแต่ไม่เคยมีเสถียรภาพ

• ProductFlavor.setDimension ซึ่งถูกแทนที่ด้วยพร็อพเพอร์ตี้ dimension

• LanguageSplitOptions ซึ่งมีประโยชน์เฉพาะสำหรับ Google Play Instant ซึ่งเลิกใช้งานแล้ว

• DensitySplit เนื่องจากระบบไม่รองรับฟีเจอร์นี้อีกต่อไป สิ่งที่ใช้แทนคือการใช้ App Bundle

API ที่นำออก

ปลั๊กอิน Android Gradle 9.0 จะนำสิ่งต่อไปนี้ออก

• AndroidComponentsExtension.finalizeDSl โดยจะแทนที่ด้วย finalizeDsl

• Component.transformClassesWith โดยจะแทนที่ด้วย Instrumentation.transformClassesWith

• Component.setAsmFramesComputationMode โดยจะแทนที่ด้วย Instrumentation.setAsmFramesComputationMode

• ComponentBuilder.enabled โดยจะแทนที่ด้วย ComponentBuilder.enable

• DependenciesInfoBuilder.includedInApk เปลี่ยนเป็น includeInApk

• DependenciesInfoBuilder.includedInBundle เปลี่ยนเป็น includeInBundle

• GeneratesApk.targetSdkVersion เปลี่ยนเป็น targetSdk

• Variant.minSdkVersion เปลี่ยนเป็น minSdk

• Variant.maxSdkVersion เปลี่ยนเป็น maxSdk

• Variant.targetSdkVersion เปลี่ยนเป็น targetSdk

• Variant.unitTest เนื่องจากใช้กับปลั๊กอิน com.android.test ไม่ได้ unitTest พร้อมใช้งานในประเภทย่อยของ VariantBuilder ที่ขยาย HasUnitTest

• VariantBuilder.targetSdk และ targetSdkPreview เนื่องจากไม่มีความหมายในคลัง โปรดใช้ GeneratesApkBuilder.targetSdk หรือ GeneratesApkBuilder.targetSdkPreview แทน

• VariantBuilder.enableUnitTest เนื่องจากใช้กับปลั๊กอิน com.android.test ไม่ได้ enableUnitTest พร้อมใช้งานในประเภทย่อยของ VariantBuilder ที่ขยาย HasUnitTestBuilder

• เราจะนำ VariantBuilder.unitTestEnabled ออกเพื่อใช้ enableUnitTest ที่มีชื่อ สอดคล้องกัน มากขึ้นในVariantBuilderประเภทย่อย ที่ขยาย HasUnitTestBuilder

• VariantOutput.enable เปลี่ยนเป็น enabled

• FeaturePlugin และ FeatureExtension ที่เลิกใช้งานและปิดใช้แล้ว

• BaseExtension.registerTransform API ที่เลิกใช้งานและปิดใช้แล้ว ซึ่ง ยังคงมีไว้เพื่ออนุญาตให้คอมไพล์กับ AGP เวอร์ชันล่าสุดในขณะที่ กำหนดเป้าหมายการทำงานบน AGP 4.2 หรือต่ำกว่า

พร็อพเพอร์ตี้ Gradle ที่นำออก

เดิมทีเราได้เพิ่มพร็อพเพอร์ตี้ Gradle ต่อไปนี้เพื่อเป็นวิธีปิดใช้ฟีเจอร์ที่เปิดใช้โดยค่าเริ่มต้นทั่วโลก

ฟีเจอร์เหล่านี้ปิดใช้งานอยู่โดยค่าเริ่มต้นตั้งแต่ AGP 8.0 หรือต่ำกว่า เปิดใช้ ฟีเจอร์เหล่านี้ในโปรเจ็กต์ย่อยที่ใช้ฟีเจอร์เหล่านี้เท่านั้นเพื่อการสร้างที่มีประสิทธิภาพมากขึ้น

android {
  buildFeatures {
    aidl = true
  }
}

android {
  buildFeatures {
    renderScript = true
  }
}

พร็อพเพอร์ตี้ Gradle ที่บังคับใช้

AGP 9.0 จะแสดงข้อผิดพลาดหากคุณตั้งค่าพร็อพเพอร์ตี้ Gradle ต่อไปนี้

ผู้ช่วยอัปเกรดปลั๊กอิน Android Gradle จะไม่อัปเกรดโปรเจ็กต์เป็น AGP 9.0 ที่ใช้พร็อพเพอร์ตี้เหล่านี้

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

ปลั๊กอิน Android Gradle 9.0.0-rc02

ปลั๊กอิน Android Gradle 9.0.0-rc01

ปลั๊กอิน Android Gradle 9.0.0-beta05

ปลั๊กอิน Android Gradle 9.0.0-beta04

ปลั๊กอิน Android Gradle 9.0.0-beta03

ปลั๊กอิน Android Gradle 9.0.0-beta02

ปลั๊กอิน Android Gradle 9.0.0-beta01

ปลั๊กอิน Android Gradle 9.0.0-alpha14

ปลั๊กอิน Android Gradle 9.0.0-alpha13

ปลั๊กอิน Android Gradle 9.0.0-alpha12

ปลั๊กอิน Android Gradle 9.0.0-alpha11

ปลั๊กอิน Android Gradle 9.0.0-alpha10

ปลั๊กอิน Android Gradle 9.0.0-alpha09

ปลั๊กอิน Android Gradle 9.0.0-alpha08

ปลั๊กอิน Android Gradle 9.0.0-alpha07

ปลั๊กอิน Android Gradle 9.0.0-alpha06

ปลั๊กอิน Android Gradle 9.0.0-alpha05

ปลั๊กอิน Android Gradle 9.0.0-alpha04

ปลั๊กอิน Android Gradle 9.0.0-alpha03

ปลั๊กอิน Android Gradle 9.0.0-alpha02

ปลั๊กอิน Android Gradle 9.0.0-alpha01