AGP 入门：基本概念、作用与发展历程

老实说，很多同学第一次接触 AGP 兼容性排查时，第一反应都是「这玩意儿到底是啥？」。今天这节，我们就从根上把 AGP 讲清楚。不绕弯子，直接切入。

AGP – Android Gradle Plugin，说白了就是 Android 项目的「编译引擎」。你的 .java、.kt、资源文件、Manifest，最后能变成可安装的 APK，全靠它调度。我在做大型模块化项目重构时，发现 80% 的 CI 构建失败最终都归因于 AGP 版本与 Gradle 版本不匹配——嗯，这就是第一课的意义。

1.1 AGP 是什么？

AGP 是 Google 官方提供的 Gradle 插件。每个 Android 项目在 build.gradle 里都会写上类似这样的配置：

// project-level build.gradle
buildscript {
    repositories {
        google()
        mavenCentral()
    }
    dependencies {
        classpath "com.android.tools.build:gradle:7.4.2"
    }
}

这个 com.android.tools.build:gradle:7.4.2 就是 AGP。它跟在 Gradle 版本后面，两个东西必须配对。我曾经遇到一次：升级 Gradle 8.0 但忘了同步升级 AGP，结果编译直接报 Unsupported major.minor version，排查了整整一下午。

1.2 AGP 的核心作用

AGP 到底做了什么？我习惯把它的工作拆成四大块，这样排查问题时思路清晰很多：

• 编译：Java/Kotlin → .class → .dex，包括 AOT 和 JIT 的预处理。
• 资源处理：合并多模块的资源文件，压缩、混淆资源 ID。
• 签名与对齐：生成签名 APK，做 zip 对齐优化。
• 测试与产物输出：生成 debug / release 包，同时产出 R.java、BuildConfig 等中间文件。

你想想看，没有 AGP，这些步骤你得自己写 Gradle Task 一个个串联。光是资源合并就能写几百行脚本，而且大概率跑不通。

1.3 发展历程：从 1.0 到 8.x

我个人经历中，AGP 4.0 到 4.2 那段是最痛苦的。迁移到 R8 后，很多自定义 ProGuard 规则直接失效，编译不出错但包体积变大。那时候我养成了一个习惯：每次升级 AGP 大版本，先跑一次完整的 assembleRelease --stacktrace，输出日志全扫一遍。

1.4 为什么 CI 中必须关注 AGP

CI 环境通常不是开发同学的本机。JVM 版本、Gradle 版本、Android SDK Build Tools 版本，这些参数在 CI 上每错一个，构建就挂。而我见过最坑的情况是：开发本地 AGP 7.4 + Gradle 8.1 跑得好好的，CI 上却莫名其妙报错。查到最后发现 CI 机器上安装的 Android SDK 里 Build Tools 版本太老，AGP 7.4 已经要求 34.0.0+。你说气不气。

1.5 知识体系总览

下面这张图把本章核心逻辑串起来了——你可以在后面各章里反复参考它：

1.6 快速自查清单

每次开始一个兼容性排查前，我会先过一遍这个清单：

1. 当前 AGP 版本号（在 build.gradle 的 classpath 里）
2. Gradle 版本（gradle-wrapper.properties 中的 distributionUrl）
3. JDK 版本（CI 和本地各看一次）
4. Android SDK Build Tools 版本（compileSdk 对应的 tools 是否齐全）
5. 是否有 org.gradle.jvmargs 配置，值是否够大

好了，这一节把 AGP 的轮廓画出来了。之后每一章都会从一个具体的兼容性故障切入，带着你一步步定位、分析、修复。记住核心逻辑：AGP 版本不是越高越好，匹配才是王道。