AndroidStudio版本和AGP版本和gradle版本以及kotlin gradle plugin版本关系梳理 2025

1 背景

你有没有发现，用最新的AndroidStudio，去打开一个老的项目，经常各种报错？

我反正是被折磨过，这原因就是AndroidStudio的版本，和AGP版本不兼容导致。所以本文梳理一下这关系。

---

2 什么是AGP，什么是 Gradle

在 Android 开发中，AGP 和 Gradle 是两个紧密相关但又有着明确区别的概念，它们共同构成了 Android 项目的构建系统。

在android项目中：

AGP版本，通常定义在

项目根目录下的 build.gradle/build.gradle.kts， 例如： com.android.tools.build:gradle:x.y.z

Gradle版本，通常定义在

项目根目录下的gradle/wrapper/gradle-wrapper.properties，例如： distributionUrl=...-gradle-x.y-bin.zip

2.1 什么是 Gradle？

Gradle 是一个开源的自动化构建工具，也是 Android 项目的核心构建引擎。但是，他不仅可以用于android项目编译，也可以用于java项目编译！！

核心作用：

自动化任务： 它可以自动化处理复杂的、重复性的软件开发任务，例如编译、打包、测试、发布、生成文档等。
依赖管理： 它负责查找、下载和配置项目所需的所有外部库（如 Kotlin 标准库、JUnit 测试库等）。
构建语言： 它使用 Groovy DSL 或 Kotlin DSL 编写的脚本（即 .gradle 或 .gradle.kts 文件）来定义项目的结构、任务和配置。

**总结：**可以把 Gradle 理解为建造房子的总工程师和一套工具集。它知道如何读取蓝图（构建脚本），如何组织工序，以及如何管理所有所需的材料和工人。

题外话：

在一个纯java的后端项目中，即可以用marven来构建打包，也可以用gradle！两者是竞争关系。
Gradle 和 Maven (Apache Maven) 两者都是业界主流的 自动化构建工具 (Build Automation Tools)。 它们的核心目标都是帮助开发者自动化和管理软件项目的构建生命周期，包括编译、依赖管理、测试、打包和部署等。

2.2 什么是 AGP？

（Android Gradle Plugin）AGP 是 Android Gradle Plugin 的缩写，中文通常译为 Android Gradle 插件。

核心作用：
Android 特定逻辑： AGP 是由 Google 的 Android 团队专门为 Android 开发编写的一组特定任务和规则。

任务执行： 它扩展了 Gradle 的能力，使其能够处理所有 Android 项目特有的复杂任务，例如：将 .java 或 .kt 文件编译成 Dalvik 字节码。将 .xml 布局和资源文件编译到 APK 中。处理和合并多个库模块的 AndroidManifest.xml 文件。生成不同配置的 APKs（例如 debug/release 版本）。

总结： 你可以把 AGP 理解为专门建造 Android 房子的专业建筑队。它使用 Gradle 这套通用工具集，但执行的是一套独特的、面向 Android 平台的专业构建工序。 它们之间的关系：AGP 是一个 Gradle 插件。Gradle 提供了通用的、可扩展的构建框架。AGP 插入到这个框架中，并提供了所有构建 Android 应用所需的功能。

---

3 Gradle版本和AGP版本关系

APG作为一个插件，它当然要求这个插件，能用于gradle的哪个版本了，所以就有了版本关系。

下面是关系图，截至025.11.11，更新请参考官方链接：https://developer.android.google.cn/build/releases/gradle-plugin?hl=zh-cn#updating-plugin

3.1 注意事项

上图的版本号，不能直接用哦，例如不能写成：

classpath "com.android.tools.build:gradle:8.10"

因为，还有个小号在后面，具体看官网：
https://developer.android.com/build/releases/past-releases/agp-8-10-0-release-notes

也就是说，如果要用AGP 8.10，实际号码得用8.10.0，即，代码得写成：

classpath "com.android.tools.build:gradle:8.10.0"

---

4 AndroidStudio和AGP的关系

AndroidStudio不停的迭代，但是不能每次能兼容支持老的AGP版本，于是又有了两者的关系。

下面是其关系图，截至2025.11.11，更多见官网：https://developer.android.com/build/releases/gradle-plugin

从上图看，好像AndroidStudio还是挺能向下兼容AGP版本的，而实际情况是，打开经常犯错。下面举个例子。

4.1 AndroidStudio打开AS工程报错

例如，我遇到一个问题，AndroidStudio 2025.2.1 打开一个工程，AGP是4（gradle版本6.1.1），按上面的图，理论上能支持，而实际却遇到了如下报错：

Your build is currently configured to use incompatible Java 21.0.7 and Gradle 6.1.1. Cannot sync the project.
We recommend upgrading to Gradle version 9.0-milestone-1.
The minimum compatible Gradle version is 8.5.
The maximum compatible Gradle JVM version is 13.

这是一个经典的三方不兼容问题，它不是因为 Android Studio 不支持老的 AGP 版本，而是因为Gradle使用的 JDK 版本太新，而项目的 Gradle 版本太旧。

日志也这么写了：

Your build is currently configured to use incompatible Java 21.0.7 and Gradle 6.1.1.

The maximum compatible Gradle JVM version is 13.

核心问题是：Gradle 6.1.1 无法在高版本的 Java 21 环境中运行。

4.1.1 根本原因分析

1. Gradle 版本太旧： Gradle 6.1.1 是一个比较老的版本（发布于 2020 年初）。根据 Gradle 的兼容性矩阵，它最高只能在 Java 13 环境下稳定运行。
2. JDK 版本太新： Android Studio 或项目配置正在使用 Java 21 来运行 Gradle 守护进程（Daemon），这远远超出了 Gradle 6.1.1 的兼容范围。

虽然 AGP 4.0 只需要 Gradle 6.1.1 或更高版本才能工作（AGP 4.0 与 Gradle 6.1.1 是兼容的），但是 Gradle 6.1.1 本身与 Java 21 是不兼容的。

4.1.2 🛠️ 解决方案（两种选择）

有两个主要的选择来解决这个问题：

选项 1：推荐方法 升级 Gradle 版本（最干净的方案）

这是最符合未来趋势和 Gradle 官方建议的方案。只需升级 Gradle Wrapper 版本，它就能在新版本的 Java 21 上运行。

1. 更新 Gradle Wrapper 版本：

   根据错误提示和当前的兼容性要求，需要将 Gradle 升级到一个支持 Java 21 的版本。

   • 官方 Gradle 兼容性显示：Gradle 8.5 及以上才完全支持 Java 21。
   • 操作： 修改项目根目录下的文件：gradle/wrapper/gradle-wrapper.properties。

   # gradle/wrapper/gradle-wrapper.properties
   # 查找并替换这一行：
   # distributionUrl=https\://services.gradle.org/distributions/gradle-6.1.1-bin.zip 
   
   # 替换为至少支持 Java 21 的版本（例如，Gradle 8.5 或更高，这里推荐使用 8.6）
   distributionUrl=https\://services.gradle.org/distributions/gradle-8.6-bin.zip

2. 同步项目：

   在 Android Studio 中点击 File > Sync Project with Gradle Files。

选项 2：临时方法 降级 Gradle 运行的 JDK 版本

如果不想升级 Gradle，那必须告诉 Android Studio 使用一个旧版本的 Java（例如 Java 11 或 Java 8）来运行 Gradle 进程。

1. 打开设置： 在 Android Studio 中，进入 File > Settings (macOS: Android Studio > Preferences)。

2. 导航到 Gradle： 搜索或导航到 Build, Execution, Deployment > Build Tools > Gradle。

3. 更改 JDK： 在 Gradle JDK 下拉菜单中，选择或配置一个旧版本的 JDK (如 Java 11 或 Java 8)。

   • 注意： Java 13 是最大兼容版本，但 Java 11 更常见且稳定。

4. 同步项目： 点击 Apply 并同步项目。

不过第二个一般不推荐，google官方建议选择选项 1，因为将 Gradle 升级到 8.x 可以带来显著的构建性能提升（例如配置缓存），并避免未来 JDK 兼容性的问题。

---

5 KGP(kotlin gradle plugin)版本和AGP的关系

在第四节的例子中，一个AS打开一个比较旧的工程，报错了，升级AGP来解决，结果改完，可能还有新的莫名报错，我这边的例子就是：

A problem occurred configuring project ':app'.
> Failed to notify project evaluation listener.
   > Could not create task ':app:compileDebugAndroidTestKotlin'.
      > Cannot use @TaskAction annotation on method AbstractKotlinCompile.execute() because interface org.gradle.api.tasks.incremental.IncrementalTaskInputs is not a valid parameter to an action method.
   > KotlinJvmAndroidCompilation with name 'debugAndroidTest' not found.

原因其实是

gradle脚本中，还有个很重要的kotlin-gradle-plugin，当你改了AGP，那就要特别注意，这个kotlin-gradle-plugin的版本，也要一起改！！！

因为他们也有依赖关系！

这是关系表，截至2025.11.11，更多请看官方文档：https://kotlinlang.org/docs/gradle-configure-project.html#apply-the-plugin