Android Studio Gradle 版本兼容性适配（理论篇）
AGP 是什么
Gradle 的专用插件
AGP 是一个 Gradle 插件，专门为 Android 项目定制，添加了 Android 特有的构建能力（如编译资源、生成 APK/AAB 文件）
Gradle扩展
gradle plugin 是基于 Gradle 构建系统的扩展工具，是辅助 gradle 主程序构建项目的
所以，不同类型的项目有不同的插件，例如 Android 有 com.android.application，java 有 java 和 java-library，spring boot 有 org.springframework.boot 等等
Android 项目的构建入口
通过在 build.gradle 中应用 com.android.application 或 com.android.library 插件，告诉 Gradle “这是一个 Android 项目”，并启用对应的构建规则。
封装 Android 构建逻辑
AGP 内部封装了 Android SDK 的构建工具链（如 aapt、dx、zipalign），简化开发者配置。
所以你看，Gradle 就像一个机器的空壳子，你往里面加什么配件，他就会出现不同的工作机制
基于 Gradle 构建的项目发展历程
在我记忆里，最早的 基于 Gradle 构建的项目一共有三个样子，我们现在只考虑后两种，也就是有了 kotlin 之后的两种
AGP 7.0之前
-
Android Studio 2020.3.1 patch3（AGP 7.0.3）
先看 build.gradle(Project)
其中两个 classpath 是 plugin 的版本，一个是 AGP，另一个是 KGPKGP
KGP 是 Kotlin Gradle plugin
Gradle 要给所有需要编译的语言添加扩展。
以前用的是 java 的时候，需要添加 Java Gradle plugin。
使用 Compose 的时候，需要添加 Compose Gradle plugin.png)
然后看 build.gradle(app)
plugins
在 AGP 7.0+ 时，使用的 plugins，而是之前是 apply plugin
这是版本更新后的语法变更，不用过多在意
.png)
-
Android Studio Ladybug Feature Drop | 2024.2.2 Patch 1 （AGP 8.8.1）
这个是出现在 gradle 使用 kotlin dsl 之后
还是先看 build.gradle(project).png)
这里的
alias是引用了/ProjectRootPath/gradle/libs.versions.toml里面设置的变量，如图所示
官方文档里提到了，您可以在 Android Studio 的 File > Project Structure > Project 菜单中指定插件版本，专指 AGP
build.gradle(app)
这里使用的还是alias引用的还是/ProjectRootPath/gradle/libs.versions.toml里面设置的变量.png)
AGP Gradle 的兼容性列表
看过了 Gradle 配置项的变化之后，你应该明白了 Gradle 配置的关键在于 AGP 以及 KGP 的版本
而且你可能听过，不要随便升级 Gradle 的建议，而且 Gradle 更新比较频繁，甚至有时候 Android Studio 新创建的项目还有兼容性配置的问题，所以了解兼容性列表必不可少
| 插件版本 | 所需的最低 Gradle 版本 |
|---|---|
| 8.9 | 8.11.1 |
| 8.8 | 8.10.2 |
| 8.7 | 8.9 |
| 8.6 | 8.7 |
| 8.5 | 8.7 |
| 8.4 | 8.6 |
| 8.3 | 8.4 |
| 8.2 | 8.2 |
| 8.1 | 8.0 |
| 8.0 | 8.0 |
| 7.4 | 7.5 |
| 7.3 | 7.4 |
| 7.2 | 7.3.3 |
| 7.1 | 7.2 |
| 7.0 | 7.0 |
| 4.2.0+ | 6.7.1 |
| 4.1.0+ | 6.5+ |
| 4.0.0+ | 6.1.1+ |
| 3.6.0 - 3.6.4 | 5.6.4+ |
| 3.5.0 - 3.5.4 | 5.4.1+ |
| 3.4.0 - 3.4.3 | 5.1.1+ |
| 3.3.0 - 3.3.3 | 4.10.1+ |
| 3.2.0 - 3.2.1 | 4.6+ |
| 3.1.0+ | 4.4+ |
| 3.0.0+ | 4.1+ |
| 2.3.0+ | 3.3+ |
| 2.1.3 - 2.2.3 | 2.14.1 - 3.5 |
| 2.0.0 - 2.1.2 | 2.10 - 2.13 |
| 1.5.0 | 2.2.1 - 2.13 |
| 1.2.0 - 1.3.1 | 2.2.1 - 2.9 |
| 1.0.0 - 1.1.3 | 2.2.1 - 2.3 |
Android Gradle 插件和 Android Studio 兼容性
| Android Studio 版本 | 所需的 AGP 版本 |
|---|---|
| Meerkat （2024.3.1） | 3.2-8.9 |
| Ladybug 功能更新（2024.2.2） | 3.2-8.8 |
| Ladybug （2024.2.1） | 3.2-8.7 |
| Koala 功能更新 （2024.1.2） | 3.2-8.6 |
| Koala （2024.1.1） | 3.2-8.5 |
| Jellyfish （2023.3.1） | 3.2-8.4 |
| Iguana （2023.2.1） | 3.2-8.3 |
| Hedgehog （2023.1.1） | 3.2-8.2 |
| Giraffe （2022.3.1） | 3.2-8.1 |
| Flamingo （2022.2.1） | 3.2-8.0 |
Gradle JDK 兼容列表
Gradle JDK 指的是运行 Gradle 所需的 JDK 环境，不是 build.gradle 里设置的 java 版本
在最新的 Android Studio 版本里，Gradle JDK 的设置步骤如下：
- 步骤一：打开 File → Settings
- 步骤二：在左侧导航栏选择 Build, Execution, Deployment → Build Tools → Gradle。
- 步骤三：在右侧的 Gradle JDK 选项中，点击下拉菜单或右侧的文件夹图标，选择已安装的 JDK 路径（如 JetBrains Runtime (JBR) 或自定义 JDK）
对于 Gradle JDK 的详细解释，可以查看 官网的这篇文章
官网的建议
在大多数情况下，我们建议使用 GRADLE_LOCAL_JAVA_HOME，这是新创建的项目的默认值。这样，您无需先打开项目，即可定义特定于项目的 JDK。
GRADLE_LOCAL_JAVA_HOME：使用
.gradle/config.properties文件中的java.home属性，默认为 JetBrains 运行时（JBR）。jdk 配置存储在项目的
.idea/gradle.xml文件中的gradleJvm选项中，其 JDK 路径解析用于在通过 Android Studio 启动时运行 Gradle。
超级提示
我特别烦恼在选择 jdk 的时候，有重复的项目
你可以在下面地址找到重复项并删除 `~/Library/Application Support/Google/AndroidStudio[版本号]/options/jdk.table.xml`
| Android | Java | 支持的 API 和语言功能 |
|---|---|---|
| 14（API 34） | 17 | 核心库 |
| 13 (API 33) | 11 | 核心库 |
| 12（API 32） | 11 | Java API |
JDK
在一开始的时候，我以为 Android 的 jdk 是和 java 项目一样，需要指定 jdk 地址的，但后来才知道，Android SDK 里包含定制的 jdk
- 标题: Android Studio Gradle 版本兼容性适配（理论篇）
- 作者: Lucas
- 创建于 : 2025-03-05 19:57:46
- 更新于 : 2025-11-20 20:48:52
- 链接: https://darkflamemasterdev.github.io/2025/03/05/Android-Studio-Gradle-版本兼容性适配（理论篇）/
- 版权声明: 本文章采用 CC BY-NC-SA 4.0 进行许可。