1. AGP 简介与配置基础

1.1 AGP 到底是个啥？

Android Gradle Plugin，圈里都叫它 AGP。说白了，它就是 Android 项目的“总包工头”。你写的 Kotlin 代码、XML 布局、图片资源、第三方库……最后能变成一个能跑的 APK 或 AAB，全靠 AGP 在背后调度。

我个人习惯把 AGP 理解成一条流水线。它先把资源打包，再编译代码，然后混淆、优化，最后签名输出。每一步都有专门的 Task 负责，AGP 就是那个确保流水线不出乱子的角色。

我在项目中遇到过好几回“编译卡死”或者“Gradle 版本不兼容”的崩溃，追根溯源，都是对 AGP 的配置理解不够深。所以第一章，咱们先把根扎稳。

核心作用一句话： AGP 负责将 Android 项目源码与资源，编译打包成可安装的应用包（APK / AAB）。

1.2 版本号规则 —— 别小看这串数字

AGP 的版本号长这样：7.4.2，分三段：

  • 主版本号（7）：大版本更新，通常伴随 Breaking Change。比如从 4.x 升到 7.x，配置改了一大堆。
  • 次版本号（4）：新功能或重要改进，一般向下兼容。
  • 补丁版本号（2）：Bug 修复，放心升。

版本背后藏着兼容性的坑。你想想看，AGP 版本和 Gradle 版本是绑死的。用错了组合，构建直接崩给你看。我曾经在某个项目里把 AGP 8.1 配上了 Gradle 7.5，结果跑一步崩一步，折腾了大半天才发现是版本没对上。

下面这张兼容表，我建议你存一下：

AGP 版本 最低 Gradle 版本 推荐 Gradle 版本 备注
8.7.x 8.9 8.11.1 最新稳定版
8.6.x 8.7 8.10.2 推荐升级
8.5.x 8.7 8.9 较老，但稳定
8.4.x 8.6 8.7 注意 API 变更
8.3.x 8.4 8.5 部分 API 弃用
8.2.x 8.2 8.4 建议升级

避坑指南： 我曾经因为 gradle-wrapper.properties 里写死了低版本 Gradle，但 AGP 却用了新版本，导致构建时抛出 Unsupported class file major version 错误。检查版本兼容性，永远是第一步。

1.3 配置入口 —— 从哪下手？

AGP 的配置分散在几个关键文件里。很多新手一上来就懵，不知道该改哪个。我一般把它们分成三层：

第一层：项目级 build.gradle

这里声明 AGP 插件本身。注意是 buildscript 块，不是 plugins 块（新项目也可以用 plugins 语法，但我个人习惯用 buildscript，更直观）。

// 项目根目录下的 build.gradle（Project 级别）
buildscript {
    repositories {
        google()
        mavenCentral()
    }
    dependencies {
        classpath "com.android.tools.build:gradle:8.6.0"
        // 注意这里的版本号要和 Gradle 兼容
    }
}

第二层：模块级 build.gradle

这里才是真正的“配置中心”。你设置的 compileSdk、minSdk、targetSdk、签名信息、混淆规则……全在这里。

// app/build.gradle（Module 级别）
plugins {
    id "com.android.application"
}

android {
    namespace "com.example.myapp"
    compileSdk 35

    defaultConfig {
        applicationId "com.example.myapp"
        minSdk 24
        targetSdk 35
        versionCode 1
        versionName "1.0"
    }

    buildTypes {
        release {
            minifyEnabled true
            proguardFiles getDefaultProguardFile("proguard-android-optimize.txt")
        }
    }
}

第三层：其他配套文件

  • settings.gradle：声明项目模块，配置插件管理仓库。
  • gradle.properties：JVM 参数、Android 构建缓存开关等全局配置。
  • local.properties：本地 SDK 路径，一般不上传到版本控制。

技巧： 我建议你创建新项目后，先把 gradle.properties 里的 org.gradle.jvmargs 改成 -Xmx4096m，能省掉很多内存不足的崩溃。别问我是怎么知道的……

1.4 AGP 构建流程一瞥

配置写好之后，AGP 到底是怎么把代码变成 APK 的？我给你画了张图，把整体框架理清楚。每次遇到构建崩溃，你都可以回到这张图上，看看是哪一步出了问题。

AGP 配置架构与构建流程 环境层 配置层 构建层 产物层 Gradle Android SDK JDK 项目级 build.gradle 模块级 build.gradle settings.gradle gradle.properties 资源处理 代码编译 混淆优化 打包 签名 APK AAB AGP 构建流程：从配置入口接收参数，按流水线依次处理，最终输出安装包。 崩溃排查时，先定位到具体环节，再检查对应配置。

从这张图里你能看到：配置层把参数传给构建层，构建层里的五个步骤是串行的，前一步的输出就是后一步的输入。最终产物要么是 APK（直接安装），要么是 AAB（上传商店）。

嗯，这里要注意一点：混淆优化这一步，很多崩溃其实是因为混淆规则没写对。我在项目里踩过好几次这个坑，后面章节咱们会专门拿案例来讲。 ← 上一章 📖 返回目录 下一章 →