Android Java Gradle 遷移指南

如果你最近將 Android Studio 升級到 Flamingo 版本，並且在執行或建置現有的 Android 應用程式時，可能會遇到類似以下的錯誤：

Caused by: org.codehaus.groovy.control.MultipleCompilationErrorsException: startup failed:

此錯誤在終端機輸出的訊息類似如下：

FAILURE: Build failed with an exception.

* Where:
Build file '…/example/android/build.gradle'
* What went wrong:
Could not compile build file '…/example/android/build.gradle'.
> startup failed:
  General error during conversion: Unsupported class file major version 61

  java.lang.IllegalArgumentException: Unsupported class file major version 61
  	at groovyjarjarasm.asm.ClassReader.<init>(ClassReader.java:189)
  	at groovyjarjarasm.asm.ClassReader.<init>(ClassReader.java:170)
  	[…
  	 …
  	 … 209 more lines of Groovy and Gradle stack trace …
  	 …
  	 …]
  	at java.base/java.lang.Thread.run(Thread.java:833)

此錯誤發生的原因是 Android Studio Flamingo 將其內建的 Java SDK 從 11 升級至 17。 Flutter 會使用 Android Studio 內建的 Java 版本 來建置 Android 應用程式。 Gradle 版本 7.3 之前 無法在 使用 Java 17 時執行。

你可以透過升級 Gradle 專案至相容版本（包含 7.3 至 7.6.1） 來修正此錯誤，方法如下所示。

請依下列步驟在 Android Studio Flamingo 中 升級 Gradle 版本：

1. 在 Android Studio 中，開啟 android 資料夾。 這將會顯示以下對話框：

   

   請將 Gradle 更新至 7.3 至 7.6.1 之間的版本（包含 7.3 與 7.6.1）。

2. 依照引導式流程完成 Gradle 更新。

   

請在你的 Flutter 專案根目錄下執行以下步驟。

1. 進入專案的 Android 目錄。

   cd android

2. 將 Gradle 更新至建議版本。請選擇 7.3 至 7.6.1（含）之間的版本。

   ./gradlew wrapper --gradle-version=7.6.1

該錯誤看起來類似於 Unsupported class file major version 65。
這表示你目前使用的 Java 版本比你執行的 Gradle 所能支援的版本還要新。
AGP（Android Gradle Plugin）、Java 與 Gradle 之間有一組不太明顯的相依關係。

最簡單的解決方式是使用 Android Studio 的 AGP 升級助手（AGP Upgrade Assistant）。
在 Android Studio 中選擇你的頂層 build.gradle 檔案，然後選擇
「工具（Tools）」->「AGP Upgrade Assistant」。

執行 flutter analyze --suggestions 來檢查你的 AGP、Java 與 Gradle 版本是否相容。
如果需要更新 Gradle，可以使用 ./gradlew wrapper --gradle-version=SOMEGRADLEVERSION 來升級，
其中 SOMEGRADLEVERSION 是版本號（你可以選擇 flutter analyze 建議的較新版本）。

要查詢目前使用的 Java 版本，請執行 flutter doctor。
在 macOS 上，你可以透過 /usr/libexec/java_home -V 查詢作業系統已知的 Java 版本。
若要設定所有 Flutter 專案使用的 Java 版本，請執行 flutter config --jdk-dir=SOMEJAVAPATH，
其中 SOMEJAVAPATH 是像 /opt/homebrew/Cellar/openjdk@17/17.0.13/libexec/openjdk.jdk/Contents/Home 這樣的 Java 版本路徑。

請留意以下幾點：

• 每個受影響的 Android 應用程式都需要重複這個步驟。
• 這個問題可能會發生在那些 沒有 透過 Android Studio 下載 Java 與 Android SDK 的使用者身上。 如果你手動將 Java SDK 升級到 17 版，但尚未升級 Gradle， 也會遇到這個問題。解決方法相同： 將 Gradle 升級到 7.3 至 7.6.1 之間的版本。
• 你的開發機器 可能 會有多個 Java SDK 副本：
  • Android Studio 應用程式內含一個 Java 版本，Flutter 預設會使用這個版本。
  • 如果你沒有安裝 Android Studio， Flutter 會依賴 shell 腳本中 JAVA_HOME 環境變數所指定的版本。
  • 如果未定義 JAVA_HOME，Flutter 會在你的路徑中尋找任何 java 可執行檔。 flutter doctor -v 指令會顯示目前使用的 Java 版本。
• 如果你將 Gradle 升級到 高於 7.6.1 的版本， 你可能（雖然機率不高）會遇到因 Gradle 變動而產生的問題，例如 已棄用的 Gradle 類別，或是 Android 檔案結構的變更，如 將 ApplicationId 從 PackageName 拆分。 如果發生這種情況，請將 Gradle 降級到 7.3 至 7.6.1 之間的版本。
• 升級到 Flutter 3.10 並不會解決這個問題。