Android Gradle 外掛程式 7.0.0 (2021 年 7 月)
Android Gradle 外掛程式 7.0.0 是主要版本,內含多種新功能及改善項目。
7.0.1 (2021 年 8 月)
這項次要更新修正了多項錯誤。如要查看重要錯誤修正清單,請參閱 版本更新網誌上的相關文章。
相容性
最低版本 | 預設版本 | 附註 | |
---|---|---|---|
Gradle | 7.0.2 | 7.0.2 | 詳情請參閱「更新 Gradle」一節。 |
SDK 版本工具 | 30.0.2 | 30.0.2 | 安裝或設定 SDK 版本工具。 |
NDK | 不適用 | 21.4.7075529 | 安裝或設定 NDK 其他版本。 |
JDK | 11 | 11 | 詳情請參閱「設定 JDK 版本」相關說明。 |
若要執行 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,藉此分析所有同時執行的依附元件模組,並產生一份報告,其中包括該應用程式及所有依附元件所產生的問題。
Groovy
// build.gradle
android {
...
lintOptions {
checkDependencies true
}
}
Kotlin
// 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
。雖然這通常表示出現錯誤,但您可能仍須忽略這項警告。忽略警示最常見的兩個原因是:
-
針對 JVM 的程式庫和缺少的類別都屬於 JVM 程式庫類別 (如上文範例所示)。
-
其中一個依附元件使用僅有編譯時間的 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 中,這類警告會變成導致建構內容故障的錯誤。如要保留 AGP 7.0 的行為,您可以在 proguard-rules.pro
檔案中新增選項 -ignorewarnings
,但不建議使用此設定。
移除 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 行為變更」。