AGP 版本升级决策与选型

AGP 版本演进历史与关键里程碑

Android Gradle Plugin（AGP）自诞生以来经历了多次重大重构。理解演进路线有助于团队在升级时评估风险与收益。下表列出近 5 个主要里程碑版本及其核心变化：

选择目标版本的决策因素

在多模块项目中，目标 AGP 版本直接影响编译速度、缓存命中率和冲突概率。决策时应综合评估以下指标：

• Gradle 版本匹配：每版 AGP 都绑定最低 Gradle 版本，升级 AGP 通常需同步升级 Gradle wrapper。
• JDK 版本要求：AGP 8.0+ 强制 JDK 17，旧项目需先升级 JDK。
• Android Studio 最低版本：新版 AGP 可能要求较新的 Studio 版本以支持新 Lint 检查或 IDE 特性。
• 第三方依赖兼容性：检查 AndroidX、Jetpack Compose、Kotlin 版本是否与目标 AGP 兼容。
• 构建缓存与增量编译：AGP 8.2 后非传递 R 类默认开启，需评估对多模块缓存的影响。
• 团队迁移成本：跳过大版本升级（如 7.4 → 8.5）可能积累更多 breaking changes。

兼容性矩阵与官方迁移指南

Google 官方提供的 AGP 兼容性矩阵是决策的核心依据。以下为整理的核心版本组合：

官方迁移指南要点概述

官方迁移指南（android-gradle-plugin-docs/upgrade-guide）强调以下关键步骤：

1. 逐版本升级：不要跨大版本直接跳，例如 7.0 → 7.2 → 8.0，每次验证编译通过。
2. 运行 lint 检查：使用 ./gradlew lint 提前发现已废弃 API 的使用。
3. 更新 namespace 配置：AGP 8.0 后 namespace 必须写在 build.gradle 的 android 块中，移除 AndroidManifest.xml 中的 package。
4. 迁移非传递 R 类：确保所有模块的 android.nonTransitiveRClass=true 统一，避免编译符号冲突。
5. 验证构建缓存：升级后首次构建会重建缓存，建议在 CI 上执行 --no-build-cache 对比构建时间。

关键的 build.gradle 配置示例

以下为在项目根 build.gradle 中声明 AGP 版本的标准方式：

// 根项目 build.gradle (Project 级别)
buildscript {
    dependencies {
        classpath "com.android.tools.build:gradle:8.5.2"
        // 其他 classpath 如 Kotlin、Hilt 等
    }
}

在 gradle-wrapper.properties 中同步更新 Gradle 版本：

distributionUrl=https\://services.gradle.org/distributions/gradle-8.9-all.zip