Android Gradle 外掛程式 7.0.0 (2021 年 7 月)

Android Gradle 外掛程式 7.0.0 是主要版本，內含多種新功能及改善項目。

相容性

若要執行 AGP 7.0，須使用 JDK 11

如要用 Android Gradle 外掛程式 7.0 建構應用程式，現在必須使用 JDK 11 才能執行 Gradle。Android Studio Arctic Fox 內已封裝 JDK 11，並設定讓 Gradle 預設使用，因此，大部分的 Android Studio 使用者都不必變更專案設定。

如果您需要手動設定 AGP 在 Android Studio 使用的 JDK 版本，則需要使用 JDK 11 以上版本。

使用獨立於 Android Studio 之外的 AGP 時，請將 JAVA_HOME 環境變數或 -Dorg.gradle.java.home 指令列選項設為 JDK 11 安裝目錄，藉此升級 JDK 版本。

請注意，如果 SDK Manager 和 AVD Manager 屬於已淘汰的 SDK 工具套件，則無法與 JDK 11 搭配使用。如要繼續將 SDK Manager 和 AVD Manager 與 AGP 7.0 以上版本搭配使用，您必須改用目前 Android SDK 指令列工具套件中的新版工具。

Variant API 穩定版

新的 Variant API 現在可以穩定運作了。請參閱 com.android.build.api.variant 套件的新介面，以及 gradle-recipes GitHub 專案內的範例。在新的 Variant API 中，我們透過「Artifacts」介面提供了許多稱為「成果」的中繼檔案。這些成果如同合併的資訊清單，可透過第三方外掛程式和程式碼安全取得並進行自訂。

我們會持續新增功能，並提供更多可供自訂的中繼成果，藉此擴充 Variant API。

Lint 行為變更

本節說明 Android Gradle 外掛程式 7.0.0 中的多項 Lint 行為變更。

改善程式庫依附性的程式碼檢查

現在用 checkDependencies = true 執行 Lint 的速度更快了。如果 Android 專案內含設有程式庫依附元件的應用程式，則建議您將 checkDependencies 設定為 true (如下所示)，並透過 ./gradlew :app:lint 執行 Lint，藉此分析所有同時執行的依附元件模組，並產生一份報告，其中包括該應用程式及所有依附元件所產生的問題。

// build.gradle
android {
  ...
  lintOptions {
    checkDependencies true
  }
}

// build.gradle.kts
android {
  ...
  lint {
    isCheckDependencies = true
  }
}

Lint 工作現在可以保持最新狀態

如果模組的來源和資源並未變更，就無須再次執行該模組的 Lint 分析工作。此時，工作的執行作業會在 Gradle 輸出內容中顯示為「UP-TO-DATE」。此次變更後，如果為含有 checkDependencies = true 的應用程式模組執行程式碼檢查，則只有變更過的模組需要進行分析。Lint 因此得以進一步提高執行速度。

如果輸入內容無變化，也不需要執行 Lint 報告工作。已知問題：當 Lint 工作顯示 UP-TO-DATE 時，stdout 不會列出任何 Lint 文字輸出內容 (問題 #191897708)。

在動態功能模組執行程式碼檢查

AGP 不再支援從動態功能模組執行 Lint。從相對應的應用程式模組執行 Lint 時，系統會在其動態功能模組上執行 Lint，並將所有問題都納入應用程式的 Lint 報表。請留意一項相關的已知問題 (問題 #191977888)：從應用程式模組使用 checkDependencies = true 執行 Lint 時，系統不會檢查動態功能程式庫依附元件，除非這些元件同時也是應用程式依附元件。

僅用預設變數執行程式碼檢查

現在執行 ./gradlew :app:lint 只會針對預設變數執行 Lint。在舊版 AGP 中，這樣做會對所有變數執行 Lint。

R8 縮減器缺少類別警示

R8 可用更精確且更一致的方式處理缺少類別情況和 -dontwarn 選項。因此，建議您著手評估 R8 發出的缺少類別警告。

當 R8 遇到未在應用程式或任一依附元件中定義的類別參照時，便會發出警告並顯示在建構輸出內容中。例如：

R8: Missing class: java.lang.instrument.ClassFileTransformer

這項警示表示系統在分析應用程式的程式碼時，找不到類別定義 java.lang.instrument.ClassFileTransformer。雖然這通常表示出現錯誤，但您可能仍須忽略這項警告。忽略警示最常見的兩個原因是：

1. 針對 JVM 的程式庫和缺少的類別都屬於 JVM 程式庫類別 (如上文範例所示)。

2. 其中一個依附元件使用僅有編譯時間的 API。

您可以在 proguard-rules.pro 檔案中新增 -dontwarn 規則，即可忽略缺少類別警示。例如：

-dontwarn java.lang.instrument.ClassFileTransformer

為了使用方便，AGP 會產生檔案，並在檔案中納入所有可能缺少的規則，然後將這些規則編寫至檔案路徑，例如：app/build/outputs/mapping/release/missing_rules.txt。只要在 proguard-rules.pro 檔案中新增規則，即可忽略警告。

在 AGP 7.0 中，缺少類別的訊息會以警告的形式顯示，您可以在 gradle.properties 中設定 android.r8.failOnMissingClasses = true，將警告改為錯誤。在 AGP 8.0 中，這類警告會變成導致建構內容故障的錯誤。您可以在 proguard-rules.pro 檔案中加入選項 -ignorewarnings，即可保留 AGP 7.0 行為，但我們不建議使用此設定。

移除 Android Gradle 外掛程式建構快取

AGP 4.1 版已移除 AGP 建構快取。先前在 AGP 2.3 推出用於補充 Gradle 建構快取的 AGP 建構快取，已完全由 AGP 4.1 的 Gradle 建構快取所取代。這項異動不會影響建構時間。

AGP 7.0 已移除 android.enableBuildCache 屬性、android.buildCacheDir 屬性和 cleanBuildCache 工作。

在專案中使用 Java 11 原始碼

您現在可以在應用程式專案中編譯 Java 11 以下版本的原始碼，這樣就能使用較新的語言功能，例如私人介面方法、匿名類別的菱形運算子，以及 lambda 參數的本機變數語法。

如要啟用這項功能，請將 compileOptions 設為所需 Java 版本，並將 compileSdkVersion 設為 30 以上：

// build.gradle
android {
  compileSdkVersion 30
  compileOptions {
    sourceCompatibility JavaVersion.VERSION_11
    targetCompatibility JavaVersion.VERSION_11
  }
  // For Kotlin projects
  kotlinOptions {
    jvmTarget = "11"
  }
}

// build.gradle.kts
android {
  compileSdkVersion(30)
  compileOptions {
    sourceCompatibility(JavaVersion.VERSION_11)
    targetCompatibility(JavaVersion.VERSION_11)
  }
  kotlinOptions {
    jvmTarget = "11"
  }
}

移除依附元件設定

我們已在 AGP 7.0 中移除下列設定 (或依附元件範圍)：

• compile
  視用途而定，已由 api 或 implementation 取代。
  也適用於 *Compile 變數，例如：debugCompile。
• provided
  已由 compileOnly 取代。
  也適用於 *Provided 變數，例如：releaseProvided。
• apk
  已由 runtimeOnly 取代。
• publish
  已由 runtimeOnly 取代。

在大多數情況下，AGP 升級小幫手會自動為專案改用新設定。

針對 Android Gradle 外掛程式進行編譯時，類別路徑會變動

針對 Android Gradle 外掛程式進行編譯時，編譯的類別路徑可能會有所變更。由於現在 AGP 內部使用 api/implementation 設定，系統可能會從編譯類別路徑中移除部分成果。如果您在編譯時需要使用 AGP 依附元件，請務必將其加入明確依附元件。

不支援在 Java 資源資料夾中加入原生程式庫

您之前可以在 Java 資源資料夾中加入原生程式庫，並用 android.sourceSets.main.resources.srcDirs 註冊資料夾，藉此將原生程式庫解壓縮並加入最終 APK。從 AGP 7.0 開始，系統不再支援此方式，且會忽略 Java 資源資料夾內的原生程式庫。請改為使用原生程式庫應該使用的 DSL 方法：android.sourceSets.main.jniLibs.srcDirs。詳情請參閱如何設定來源集。

已知問題

本節說明 Android Gradle 外掛程式 7.0.0 的已知問題。

1.4.x Kotlin Multiplatform 外掛程式不相容性

Android Gradle 外掛程式 7.0.0 可與 Kotlin Multiplatform 外掛程式 1.5.0 以上版本相容。使用 Kotlin Multiplatform 支援功能的專案必須更新至 Kotlin 1.5.0 版，才能使用 Android Gradle 外掛程式 7.0.0。如要解決這個問題，您可以將 Android Gradle 外掛程式降級至 4.2.x 版，但不建議這樣做。

詳情請參閱 KT-43944。

缺少程式碼檢查輸出內容

當 Lint 工作顯示「UP-TO-DATE」時，stdout 不會列出任何 Lint 文字輸出內容 (問題 #191897708)。詳情請參閱「Lint 行為變更」。Android Gradle 外掛程式 7.1 會修正此問題。

並非所有動態功能程式庫依附元件皆有進行程式碼檢查

從應用程式模組使用 checkDependencies = true 執行 Lint 時，系統不會檢查動態功能程式庫依附元件，除非這些元件同時也是應用程式依附元件 (問題 #191977888)。您可以在這些程式庫執行程式碼檢查工作，藉此解決問題。詳情請參閱「Lint 行為變更」。