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 不会解决此问题。