AGP

AGP 是 Android Gradle Plugin（Android Gradle 插件） 的缩写，它是 Google 官方为 Android 项目提供的 Gradle 构建插件，用于将标准的 Gradle 构建系统适配到 Android 应用的编译、打包、测试等流程中。

AGP 在项目中的位置

在build.gradle文件中体现：

1. 项目级 build.gradle（声明 AGP 版本）

// build.gradle (Project)
buildscript {
    dependencies {
        classpath 'com.android.tools.build:gradle:8.5.0' // ← 这就是 AGP
    }
}

或使用现代插件 DSL（推荐）：

// build.gradle.kts (Project)
plugins {
    id("com.android.application") version "8.5.0" apply false
    id("org.jetbrains.kotlin.android") version "1.9.20" apply false
}

2. 模块级 build.gradle（应用 AGP 插件）

// app/build.gradle
plugins {
    id 'com.android.application' // ← 应用 AGP 的 application 插件
}

或者老式写法：

apply plugin: 'com.android.application'

AGP 提供的主要插件类型

AGP 与 Gradle、Android Studio 的关系

版本必须匹配：
每个 AGP 版本只支持特定范围的 Gradle 版本。
例如：

• AGP 8.5.x → 需要 Gradle 8.6+
• AGP 8.0.x → 需要 Gradle 8.2+

官方兼容性表格：\ https://developer.android.com/build/releases/gradle-plugin#compatibility

AGP 的核心配置块（在android {}中）

在模块级build.gradle中，会看到：

android {
    compileSdk 34
    namespace "com.example.app"
 
    defaultConfig {
        minSdk 24
        targetSdk 34
        versionCode 1
        versionName "1.0"
    }
 
    buildTypes {
        release {
            minifyEnabled true
            proguardFiles getDefaultProguardFile("proguard-android.txt"), "proguard-rules.pro"
        }
    }
 
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_17
        targetCompatibility JavaVersion.VERSION_17
    }
 
    buildFeatures {
        viewBinding true
        compose true
    }
}

这些配置都是由 AGP 解析并驱动构建流程的。

AGP 的重要演进（近年亮点）

常见问题

Q：Gradle、Gradlew 以及 AGP 有什么关系？有什么区别？

A：这三者构成了 Android 项目的构建流水线。

• Gradle：一个通用的构建工具。它不只为 Android 服务，Java、Kotlin、C++ 甚至 iOS 项目都能用它。它负责管理依赖、运行任务（Task）以及定义构建生命周期。
• Gradlew (Gradle Wrapper)：它是 Gradle 的包装器。就是一个脚本（Windows 下是gradlew.bat，Mac/Linux 下是gradlew）。它的作用是确保每个开发者（以及服务器）都使用完全相同版本的 Gradle，避免“我电脑上能跑，你那里不行”的问题。
• AGP (Android Gradle Plugin)：它是 Gradle 的一个插件。Gradle 本身并不知道如何编译.dex文件或打包 APK，Google 开发了 AGP 注入到 Gradle 中，给它增加了处理 Android 资源、签名、混淆等专属功能。

Q：AGP 和 Android SDK 有什么关系？

A：AGP 使用 Android SDK 中的工具（如aapt2、dx/d8、zipalign）来完成实际构建，但它本身是独立的 Gradle 插件。

Q：如何升级 AGP？

1. 修改build.gradle中的版本号；
2. 根据 官方迁移指南 调整配置；
3. 同步 Gradle 版本（修改 gradle/wrapper/gradle-wrapper.properties）。

Q：AGP 开源吗？

是的！源码在 AOSP：https://cs.android.com/android/platform/superproject/+/master:tools/base/

Q：AAR、APK 以及 JAR 什么关系？

A：这三者是不同阶段生成的压缩包产物（其实都是 ZIP 格式）。

• JAR (Java Archive)：最纯粹。 里面只包含编译后.class字节码和一些配置文件。它不能包含 Android 的资源文件（如布局 Layout、图片 Drawable）。
• AAR (Android Archive)：Android 专属库。 它是为了弥补 JAR 的不足而生的。除了包含代码（通常是一个嵌套在内的classes.jar），还包含了 Android 的资源、清单文件（Manifest）甚至是 C/C++ 库。它是 Module 的产物，供其他 App 调用。
• APK (Android Package)：最终成品。它是可以直接安装在手机上的包。它把所有的代码（转成了.dex格式）、资源、签名信息全部打包在一起。

Q：它们如何协作的？

A：过程如下：

• 通过 Gradlew 调用构建命令
• Gradle 引擎启动，加载 AGP 插件
• AGP 告诉 Gradle 怎么处理你的源代码和资源
• 如果你写的是工具类，可能会被打成 JAR
• 如果你写的是带界面的库，会被打成 AAR
• 如果你写的是一个 App，Gradle 会把所有的代码、JAR 和 AAR 揉在一起，最终吐出一个 APK

Q：什么是.dex？

A：.dex文件是 Android 平台的“可执行文件”，全称是 Dalvik Executable。在传统的 Java 环境中，每个.java文件编译后会生成一个独立的.class文件，会造成几个问题：

• 重复信息多： 每个.class文件都有自己的常量池，如果一个项目有 1000 个类，很多基础字符串（如java/lang/String）就会在 1000 个文件中重复出现。
• 占用空间大： 重复信息会导致安装包（APK）臃肿，且手机加载时需要频繁读取多个文件，效率低。

而Android SDK 中的工具（如d8或旧版的dx）会将所有的.class文件整合并压缩成一个（或几个）.dex文件：

• 去重合并： 它将所有类的常量池合并在一起，相同的字符串和常量只存储一份。
• 寄存器架构： 与 JVM 的“栈架构”不同，Android 的虚拟机（Dalvik 或 ART）采用“寄存器架构”。这种方式生成的指令更少，执行效率更高，更适合移动设备。
• 紧凑布局：.dex格式专门为共享数据设计，极大地减小了代码占用的空间。

混淆（R8）、签名、Lint 检查

混淆（R8）、签名（Signing）和 Lint 检查是 Android 应用构建和发布流程中的关键环节，分别用于代码保护、身份认证和代码质量保障。

1. 混淆（Obfuscation）—— 由 R8 实现

混淆是指在构建 Release 版本时，将你的源代码中的类名、方法名、变量名等替换为无意义的短名称（如a, b, c），使反编译后的代码难以阅读和理解。

目的：

• 防止他人轻易逆向工程你的 App
• 减小 APK/AAB 体积（移除无用代码 + 名称缩短）

谁来做？—— R8

• Google 官方工具，集成在 AGP 中（从 Android Studio 3.4 开始默认启用）。
• R8 = ProGuard 的继任者，功能更强、速度更快。
• 它同时完成三件事：
  1. Shrinking（压缩）：删除未使用的类、方法、字段；
  2. Obfuscation（混淆）：重命名保留的代码；
  3. Optimization（优化）：简化字节码（如内联方法）。

如何启用？

在模块级build.gradle中：

android {
    buildTypes {
        release {
            minifyEnabled true          // 启用 R8
            shrinkResources true        // 同时移除未使用的资源（可选）
            proguardFiles getDefaultProguardFile("proguard-android-optimize.txt"),
                "proguard-rules.pro" // 自定义规则文件
        }
    }
}

注意事项

• 第三方库或反射调用的类必须加白名单，否则运行时会崩溃。
• 自定义规则写在proguard-rules.pro中

例如：

# 保留某个类不被混淆
-keep class com.example.MyKeepClass { *; }
# 保留所有 Activity（因 AndroidManifest 中通过字符串引用）
-keep public class * extends android.app.Activity

构建后，可以在app/build/outputs/mapping/release/找到mapping.txt，用于反混淆崩溃日志。

2. 签名（Signing）

数字签名是 Android 系统用来验证 App 身份和完整性的机制。每个安装到设备上的 APK 必须经过签名，否则无法安装。

为什么需要？

• 唯一标识开发者：系统通过签名区分不同开发者（即使包名相同）
• 允许覆盖安装：只有相同签名的 APK 才能升级已安装应用
• 权限共享：同一签名的不同 App 可共享数据（通过sharedUserId）
• Google Play 要求：上传 AAB 必须使用正式签名

两种签名类型

如何配置正式签名？

1. 生成密钥库（Keystore）：

keytool -genkey -v -keystore my-release-key.jks -keyalg RSA -keysize 2048 -validity 10000 -alias my-key-alias

2. 在build.gradle中引用：

android {
    signingConfigs {
        release {
            storeFile file("my-release-key.jks")
            storePassword "your_store_password"
            keyAlias "my-key-alias"
            keyPassword "your_key_password"
        }
    }
    buildTypes {
        release {
            signingConfig signingConfigs.release
        }
    }
}

重要安全提示：

• 不要将密码明文写在build.gradle中，建议使用gradle.properties或环境变量。
• 密钥一旦丢失，无法更新已有应用（Google Play 支持“密钥升级”但流程复杂）。

3. Lint 检查

Lint 是 Android 官方提供的静态代码分析工具。它在不运行代码的情况下，扫描你的项目，找出：

• 潜在 Bug（如空指针、资源泄漏）
• 性能问题（如主线程 I/O）
• 安全漏洞（如硬编码敏感信息）
• 国际化/无障碍问题
• 代码风格与最佳实践违规

谁来执行？

• 集成在 Android Studio 中（实时高亮警告）；
• 也可通过命令行运行：./gradlew lint

如何配置？

在build.gradle中：

android {
    lint {
        abortOnError false          // Lint 错误是否中断构建
        checkReleaseBuilds true     // 是否在 release 构建时检查
        disable 'MissingTranslation', 'HardcodedText' // 禁用某些检查
        enable 'UnusedResources'    // 强制启用某些检查
        htmlOutput file("lint-report.html") // 生成报告
    }
}

📊 输出结果

• 在 Android Studio 中：红色波浪线 + 问题面板
• 命令行：生成 HTML/XML 报告（默认在 app/build/reports/lint-results.html）

💡 示例问题

建议：将 Lint 集成到 CI 流程中，确保主干代码质量。

三者关系总结

它们通常在 Release 构建流程中依次发生：

代码 → Lint 检查 → 编译 → R8 混淆/压缩 → 签名 → 生成 APK/AAB

✅ 最佳实践建议

1. Release 包必须开启 R8 + 正式签名；
2. **Lint 错误应设为**** **abortOnError true（团队强制规范）；
3. 混淆规则要随第三方库更新及时维护；
4. 签名密钥由专人保管，禁止提交到 Git；
5. 利用 mapping.txt 和 lint-report.html 做发布归档。

AGP 完整学习路径（从入门到进阶）

✅ 阶段 1：基础认知（1~2 天）

目标：理解 AGP 是什么、在哪配置、基本结构

• 了解 Gradle 与 AGP 的关系
• 区分 项目级 vs 模块级 build.gradle
• 学会配置 compileSdk、minSdk、targetSdk
• 理解 buildTypes 和 productFlavors
• 掌握依赖写法：implementation、api、debugImplementation 等

📌 实践任务：

// 创建一个带 flavor 的 app 模块
android {
    flavorDimensions "version"
    productFlavors {
        free { dimension "version" }
        pro  { dimension "version" }
    }
}

✅ 阶段 2：核心配置与优化（3~5 天）

目标：掌握常用配置项，提升构建效率

• 配置 Java/Kotlin 版本（compileOptions / kotlinOptions）
• 启用 ViewBinding / DataBinding / Jetpack Compose
• 配置 ProGuard / R8 混淆规则
• 理解 sourceSets（自定义资源/代码目录）
• 使用 lintOptions 控制代码检查
• 了解 buildFeatures 开关（如 aidl, renderScript）

📌 关键概念：

• Variant（变体） = Build Type + Flavor 的组合（如 freeDebug）
• Task DAG：AGP 自动生成大量 task（如 assembleDebug, bundleRelease）

✅ 阶段 3：高级主题（1~2 周）

目标：解决复杂构建问题，定制化流程

• 自定义 Task 并挂载到 AGP 生命周期（如 preBuild.doLast {}）
• 使用 androidComponents API（AGP 7.0+ 新扩展点）
• 多模块项目依赖管理（避免循环依赖）
• 构建缓存（Build Cache）、增量编译原理
• 性能分析：使用 —profile、gradle-profiler
• 迁移到 Version Catalog（libs.versions.toml） 统一依赖版本

📌 示例：在打包前动态修改 versionName

androidComponents.onVariants { variant ->
    variant.outputs.forEach { output ->
        output.versionName.set("2.0-custom")
    }
}

✅ 阶段 4：源码与原理（可选，进阶）

目标：深入理解 AGP 内部机制

• 阅读 AGP 官方设计文档
• 调试 AGP 源码（通过 AOSP 或 decompiled jar）
• 理解 Transform API（已废弃） vs 新的 Artifact API
• 编写自定义 Gradle 插件集成 AGP

📚 三、权威官方文档（按优先级排序）

🔧 四、实用工具 & 调试技巧

💡 五、常见误区提醒

• ❌ 不要直接在 build.gradle 顶层写文件 I/O 操作（会在 Sync 时执行！）
• ❌ 避免使用已废弃的 compile、apk 依赖配置
• ❌ 不要随意升级 AGP 而不看迁移指南（常有 Breaking Changes）
• ✅ 推荐使用 KTS（Kotlin DSL） 替代 Groovy（类型安全、自动补全更好）

🎁 附加：推荐学习顺序清单

1. 通读 Android 构建概述
2. 动手创建一个多 Flavor 项目
3. 尝试启用 R8 混淆并验证 APK
4. 使用 libs.versions.toml 管理依赖
5. 阅读最新 AGP 版本的 Release Notes
6. 用 —profile 分析一次完整构建耗时

更新: 2026-01-09 17:25:37
原文: https://www.yuque.com/dongpozhouzi-mshe3/zhm85g/vbhfnvngsimgry7h

相关笔记

• BuildConfig
• 变体Variant
• 源码集sourceSet
• Gradle插件配置