Android开发-AGP版本配置及与Gradle关系(Android Studio版本选择)

前言

AGP（Android Gradle Plugin，Android Gradle 插件）是 Android 开发中非常核心的工具组件，主要作用是：

1. 连接 Android 项目与 Gradle 构建系统：将 Android 特有的构建逻辑（如编译 Java/Kotlin 代码、打包 APK/AAB、处理资源文件、混淆代码等）集成到 Gradle 构建流程中。
2. 提供 Android 专属构建功能：比如支持多渠道打包、依赖管理、NDK 集成、ProGuard 混淆、签名配置等 Android 开发特有的需求。
3. 适配 Android SDK 和工具链：随着 Android 系统和开发工具的更新，AGP 会同步支持新的 API、编译选项和开发特性。

AGP 与 Android Studio 的兼容关系

https://developer.android.google.cn/studio/releases?hl=zh-cn

AGP 和 Android Studio 是协同工作的紧密关联组件，它们的版本兼容性遵循以下规则：

版本匹配原则：

• 每个 Android Studio 版本都有其推荐或支持的 AGP 版本范围（通常会向前兼容几个旧版本，但不支持过于超前的版本）。
• 例如：Android Studio Hedgehog（2023.1.1）推荐 AGP 8.2.x，而 Android Studio Iguana（2023.2.1）则推荐 AGP 8.3.x。

兼容性限制：

• 若使用的 AGP 版本高于当前 Android Studio 支持的最高版本，会出现类似你遇到的兼容性错误。
• 若 AGP 版本过低，可能无法支持 Android Studio 的新功能，或无法构建基于新版本 SDK 的项目。

升级联动性：

• 升级 Android Studio 后，通常需要同步升级 AGP 到推荐版本（IDE 会提示）。
• 升级 AGP 时，也可能需要同步升级 Gradle 版本（AGP 依赖特定的 Gradle 版本）。

简单来说：

Android Studio 是开发 IDE，AGP 是负责 Android 项目构建的工具插件，二者版本需要匹配才能确保开发和构建过程顺畅。如果版本不兼容，会导致项目无法同步、构建失败等问题。

版本对应关系

Android Studio 版本	AGP 版本	最低支持 Gradle 版本	推荐 JDK 版本	推荐 Kotlin 版本
Hedgehog (2023.1.1)	3.2-8.2	8.2	JDK 17	1.9.x
Iguana (2023.2.1)	3.2-8.3	8.4	JDK 17	1.9.x/2.0.x
Jellyfish (2024.1.1)	3.2-8.5	8.6	JDK 17	2.0.x
Koala (2024.2.1)	3.2-8.7	8.7	JDK 17	2.0.x
Narwhal (2025.1.3)	4.0-8.13	8.13	JDK 17	2.0.x

低版本的Android Studio不能使用高版本的AGP。

高版本的Android Studio能兼容低版本的AGP，会提示升级AGP。

Android Studio 和 AGP 的最低版本如下所示：

API 级别	最低 Android Studio 版本	最低 AGP 版本
36.1	Narwhal 3 功能更新 \	2025.1.3	8.13.0
36.0	Meerkat \	2024.3.1 Patch 1	8.9.1
35	Koala 功能更新 \	2024.2.1	8.6.0
34	Hedgehog \	2023.1.1	8.1.1
33	Flamingo \	2022.2.1	7.2

更换AGP版本

如果我们的Android Studio版本低，要打开高版本的项目，就需要降低AGP版本，Gradle版本不用降低。

gradle => libs.versions.toml

[versions]
agp = "8.12.1"

[plugins]
android-application = { id = "com.android.application", version.ref = "agp" }

build.gradle.kts 中使用

plugins {
    alias(libs.plugins.android.application) apply false
}

Android Studio版本选择

如果是新项目

可以使用新版本的Android Studio。

如果要打开老项目

不要使用最新版本的Android Studio。

比如2025.1已经不支持kotlinx.android.synthetic，导致项目代码全都报错，必须迁移至View Binding。

常见问题

修改代码运行不产生效果

勾选下面的这一项即可。

BuildConfig.DEBUG not found

AGP 8.0 及以后的版本中，默认禁用了 buildConfig，在以前的版本中，这个功能默认是启用的，允许你在代码里通过 BuildConfig 类访问一些自动生成的构建配置常量。

在 AGP 8.0+ 版本中想继续使用，需要在模块级别的 build.gradle 中明确启用：

android {
    // 加上这个
    buildFeatures {
        buildConfig = true
    }
}