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 資料夾。這將顯示以下對話方塊：

   

   升級到 7.3 到 7.6.1 之間的 Gradle 版本。

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、Java 和 Gradle 之間存在一組不易察覺的依賴關係。

解決此問題的最簡單方法是使用 Android Studio AGP 升級助手。要使用它，請在 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。在 Mac 上，您可以使用 /usr/libexec/java_home -V 查詢作業系統已知的 Java 版本。要設定所有 Flutter 專案使用的 Java 版本，請執行 flutter config --jdk-dir=SOMEJAVAPATH，其中 SOMEJAVAPATH 是指向 Java 版本的路徑，例如 /opt/homebrew/Cellar/openjdk@17/17.0.13/libexec/openjdk.jdk/Contents/Home。

以下是一些需要注意的事項：

• 對每個受影響的 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 分離。如果發生這種情況，請降級到 7.3 到 7.6.1 之間的 Gradle 版本。
• 升級到 Flutter 3.10 不會解決此問題。