Android Studio Gradle 插件要求 Java 11 的解决方案

问题描述

当您尝试在 Android Studio 中运行 Android Jetpack Compose 项目时，可能会遇到以下错误：

> Failed to apply plugin 'com.android.internal.application'.
> Android Gradle plugin requires Java 11 to run. You are currently using Java 1.8.
You can try some of the following options:
- changing the IDE settings.
- changing the JAVA_HOME environment variable.
- changing `org.gradle.java.home` in `gradle.properties`.

这个错误表明您的项目配置需要 Java 11 来运行 Android Gradle 插件，但当前系统使用的是 Java 1.8。

解决方案

以下是几种有效的解决方案，适用于不同的开发环境和使用场景。

方法一：在 Android Studio 中修改 Gradle JDK 设置（推荐）

这是最简单直接的解决方案：

1. 打开 Android Studio
2. 进入菜单：File → Settings (Windows/Linux) 或 Android Studio → Preferences (macOS)
3. 导航到：Build, Execution, Deployment → Build Tools → Gradle
4. 在 Gradle JDK 选项中选择 Java 11 或更高版本
5. 点击 Apply 然后 OK
6. 重新构建项目

INFO

此方法适用于大多数情况，是首选的解决方案。

方法二：在 gradle.properties 文件中配置 Java 主目录

如果方法一不起作用，可以在项目的 gradle.properties 文件中添加以下配置：

org.gradle.java.home=<您的Java11路径>

路径示例：

• Windows:

  org.gradle.java.home=C\:\\Program Files\\Java\\jdk-11.0.15

• macOS:

  org.gradle.java.home=/Library/Java/JavaVirtualMachines/jdk-11.0.10.jdk/Contents/Home

• Linux:

  org.gradle.java.home=/usr/lib/jvm/java-11-openjdk-amd64

方法三：设置系统环境变量

Windows 系统

1. 打开系统环境变量设置
2. 创建或修改 JAVA_HOME 变量，指向 Java 11 安装路径
3. 在 Path 变量中添加 %JAVA_HOME%\bin
4. 重启 Android Studio

使用命令行设置（管理员权限）：

setx /M JAVA_HOME "C:\Program Files\Java\jdk-11.0.11"

WARNING

如果路径包含空格（如 "Program Files"），在环境变量中使用 Progra~1 替代：

setx /M JAVA_HOME "C:\Progra~1\Java\jdk-11.0.11"

macOS 系统

编辑 shell 配置文件（如 ~/.zshrc 或 ~/.bash_profile）：

export JAVA_HOME="/Applications/Android Studio.app/Contents/jbr/Contents/Home"

然后运行：

source ~/.zshrc  # 或 source ~/.bash_profile

验证设置：

echo $JAVA_HOME

方法四：检查全局 Gradle 配置

有时全局 Gradle 配置会覆盖项目设置：

1. 前往 ~/.gradle/ 目录（Windows: C:\Users\<用户名>\.gradle）
2. 打开 gradle.properties 文件
3. 检查并修改 org.gradle.java.home 设置，或删除该行

方法五：降级 Android Gradle 插件（不推荐）

如果您暂时不想升级到 Java 11，可以降级 Android Gradle 插件版本：

// 在 build.gradle 文件中
plugins {
    id 'com.android.application' version '4.2.0' apply false
    id 'com.android.library' version '4.2.0' apply false
}

DANGER

降级插件版本可能导致无法使用最新功能，建议优先升级 Java 版本。

不同环境的特殊配置

Flutter 项目

对于 Flutter 项目，需要在 android/gradle.properties 中添加：

org.gradle.java.home=<Java11路径>

CI/CD 环境配置

GitHub Actions

- name: Set up JDK 11
  uses: actions/setup-java@v3
  with:
    distribution: 'zulu'
    java-version: 11

Azure Pipelines

- task: JavaToolInstaller@0
  inputs:
    versionSpec: '11'
    jdkArchitectureOption: 'x64'
    jdkSourceOption: 'PreInstalled'

MS App Center

在构建配置的环境变量中设置：

JAVA_HOME = $(JAVA_HOME_11_X64)

验证解决方案

应用任何解决方案后，验证配置是否正确：

1. 在终端中运行：

   ./gradlew --version

2. 检查输出中的 JVM 版本是否为 11 或更高：

   JVM: 11.0.12 (JetBrains s.r.o. 11.0.12+0-b1504.28-7817840)

常见问题排查

1. Android Studio 终端仍使用旧版本 Java
   即使正确设置了 IDE 配置，终端可能仍使用系统默认 Java 版本。需要通过环境变量单独配置。

2. 路径中包含空格
   Windows 系统中，路径中的空格可能导致问题，可以使用缩写形式（如 Progra~1）或确保路径用引号括起来。

3. 多个 Java 版本共存
   确保所有相关配置（系统变量、IDE 设置、Gradle 配置）都指向同一个 Java 11 安装。

总结

Android Gradle 插件从 7.0 版本开始要求 Java 11，这是为了支持最新的语言特性和性能改进。通过上述任一方法配置 Java 11 环境，即可解决兼容性问题并顺利构建项目。

TIP

建议使用 Android Studio 内置的 JDK（位于 Android Studio.app/Contents/jbr/Contents/Home），这可以避免版本冲突问题。

正确配置后，您的项目将能够充分利用 Java 11 的新特性，同时确保构建过程的稳定性和兼容性。