AGP 迁移指南

源：Android 官方文档 - AGP 版本说明

Android Gradle Plugin (AGP) 随着版本更新会引入新功能和破坏性变更。本文档详细说明每个大版本的迁移步骤。

版本兼容性

AGP 与 Gradle 版本对应

AGP 版本	最低 Gradle	推荐 Gradle	最低 JDK	最高 API Level
9.0	9.1	9.4	17	36
8.7	8.9	8.11.1	17	35
8.0	8.0	8.2	17	34
7.4	7.5	7.6	11	33
7.0	7.0	7.2	11	31

迁移到 AGP 9.0 2026年1月

AGP 9.0 是重大更新，引入了内置 Kotlin 支持和新 DSL 接口。

关键破坏性变更

内置 Kotlin 支持 重大变更

AGP 9.0 内置 Kotlin 支持，默认启用。无需再手动应用 Kotlin 插件。

迁移前（AGP 8.x）：

plugins {
    id("com.android.application")
    id("org.jetbrains.kotlin.android") version "2.1.0"  // 需要显式声明
}

迁移后（AGP 9.0）：

plugins {
    id("com.android.application")  // Kotlin 支持已内置
   // 移除 kotlin-android 插件
}

⚠️ 临时退出（不推荐）:

# gradle.properties
android.builtInKotlin=false  # 将在 AGP 10.0 移除

新 DSL 接口仅实现公共接口

AGP 9.0 仅实现新的公共 DSL 接口，旧的内部 DSL 类型不再被识别。

废弃的 API：

// ❌ 废弃：applicationVariants API
android.applicationVariants.all { variant ->
    // 旧的 variant API
}

新的 API：

// ✅ 使用：androidComponents API
androidComponents {
    onVariants { variant ->
        // 新的 variant API
    }
}

Kotlin运行时依赖

AGP 9.0 对 Kotlin Gradle Plugin (KGP) 有运行时依赖。

升级 KGP：

// settings.gradle.kts
pluginManagement {
    plugins {
        kotlin("android") version "2.1.10"  // 使用更高版本的KGP
    }
}

降级 KGP（不推荐）：

# gradle.properties
android.experimental.kgpVersion=2.0.0  # 降级到特定版本

详细迁移步骤

更新 Gradle 和 AGP：

# 更新 Gradle Wrapper
./gradlew wrapper --gradle-version 9.4

// build.gradle.kts (project)
plugins {
    id("com.android.application") version "9.0.0" apply false
    id("com.android.library") version "9.0.0" apply false
}

移除 Kotlin Android 插件：

从所有模块的 build.gradle.kts 中移除：

// ❌ 移除
id("org.jetbrains.kotlin.android")

更新自定义构建逻辑：

替换所有使用旧 Variant API 的代码。

迁移前：

android.applicationVariants.all { variant ->
    val variantName = variant.name
    variant.outputs.forEach { output ->
        // 自定义输出
    }
}

迁移后：

androidComponents {
    onVariants { variant ->
        val variantName = variant.name
        variant.artifacts.use(/* ... */)
    }
}

更新第三方插件：

确保所有插件兼容 AGP 9.0：

• Hilt Gradle Plugin 2.50+
• KSP 2.1.0-1.0.29+
• Firebase Crashlytics Gradle Plugin 3.0.2+

处理已移除的 API：

查看 AGP 9.0 发布说明 检查使用的 API 是否被移除。

临时兼容性标志（仅用于测试）：

# gradle.properties
android.builtInKotlin=false  # 禁用内置 Kotlin（临时）
android.newDsl=false  # 使用旧DSL（临时）

⚠️ 警告：这些标志将在 AGP 10.0 中移除！

Kotlin Multiplatform 项目迁移

如果您使用 Kotlin Multiplatform，迁移更复杂。

使用新的 Android KMP 库插件：

// 旧方式（不兼容AGP 9.0）
plugins {
    kotlin("multiplatform")
    id("com.android.library")
}

// 新方式
plugins {
    kotlin("multiplatform")
    id("com.android.kotlin.multiplatform.library")  // 新插件
}

详细迁移步骤请参考 Kotlin 官方文档。

已移除的功能

• android.dataBinding.addDefaultAdapters
• android.dataBinding.addKtx
• BuildConfig 默认值改为 false
• Variant API 旧接口

---

迁移到 AGP 8.0 2023年4月

AGP 8.0 是一个重大版本，强制要求 Namespace、JDK 17，并改变了多个默认值。

关键破坏性变更

Namespace 必需 破坏性变更

AGP 8.0 要求在 build.gradle.kts 中定义 namespace，不能仅在 AndroidManifest.xml 中定义。

迁移前（AGP 7.x）：

<!-- AndroidManifest.xml -->
<manifest package="com.example.myapp">

迁移后（AGP 8.0+）：

build.gradle.kts

android {
    namespace = "com.example.myapp"  // 必须设置
    compileSdk = 34
}

AndroidManifest.xml

<manifest>
    <!-- package 属性可选 -->
</manifest>

JDK 17 必需

AGP 8.0 要求 JDK 17 运行。

配置方式：

# gradle.properties
org.gradle.java.home=/path/to/jdk-17

或在 Android Studio： Preferences → Build, Execution, Deployment → Build Tools → Gradle → Gradle JDK → 选择 JDK 17

BuildConfig 默认禁用

AGP 8.0 起，BuildConfig 类默认不生成。

错误示例：

Unresolved reference: BuildConfig

解决方法：

android {
    buildFeatures {
        buildConfig = true  // 启用 BuildConfig
    }
}

默认值变更

以下属性默认值已改变，可能影响您的构建：

# gradle.properties

# BuildConfig 默认禁用
android.defaults.buildfeatures.buildconfig=false  # 旧：true

# AIDL 默认禁用
android.defaults.buildfeatures.aidl=false  # 旧：true

# RenderScript 默认禁用
android.defaults.buildfeatures.renderscript=false  # 旧：true

# 非常量 R 类启用
android.nonFinalResIds=true  # 旧：false

# 非传递性 R 类启用
android.nonTransitiveRClass=true  # 旧：false

# R8 Full Mode 启用
android.enableR8.fullMode=true  # 旧：false

迁移建议：

1. 检查是否使用了上述功能
2. 如需要，在 gradle.properties 中显式设置回旧值
3. 或更新代码适配新默认值

强制执行的属性

以下属性值被强制执行，无法更改：

# gradle.properties（设置这些值会被忽略并警告）

android.r8.failOnMissingClasses=true  # 强制为 true
android.enableArtProfiles=true  # 强制为 true
android.enableNewResourceShrinker=true  # 强制为 true

详细迁移步骤

更新 Gradle Wrapper：

./gradlew wrapper --gradle-version 8.2

更新 AGP 版本：

build.gradle.kts

plugins {
    id("com.android.application") version "8.7.3"
    id("org.jetbrains.kotlin.android") version "2.1.0"
}

build.gradle

buildscript {
    dependencies {
        classpath 'com.android.tools.build:gradle:8.7.3'
    }
}

更新 JDK 到 17：

验证 JDK 版本：

java -version

为所有模块添加 namespace：

// app/build.gradle.kts
android {
    namespace = "com.example.myapp"
}

// mylibrary/build.gradle.kts
android {
    namespace = "com.example.mylibrary"
}

处理测试 namespace 冲突：

如果测试 namespace 与主 namespace 相同，需要手动修改：

android {
    namespace = "com.example.myapp"
    testNamespace = "com.example.myapp.test"  // 修改测试 namespace
}

启用 BuildConfig（如需要）：

android {
    buildFeatures {
        buildConfig = true
    }
}

更新 R8 ProGuard 规则：

由于 android.r8.failOnMissingClasses=true，所有缺失类警告现在会导致构建失败。

添加必要的 -dontwarn 规则：

# proguard-rules.pro
-dontwarn java.lang.instrument.ClassFileTransformer

或查看生成的 missing_rules.txt：

app/build/outputs/mapping/release/missing_rules.txt

使用 AGP Upgrade Assistant

Android Studio 提供升级助手：

Tools → AGP Upgrade Assistant

自动检测和修复：

• Namespace 缺失
• BuildConfig 引用
• 版本兼容性问题
• 废弃 API 使用

---

迁移到 AGP 7.0 2021年7月

AGP 7.0 引入 JDK 11 要求和新的 Variant API。

关键变更

JDK 11 必需

AGP 7.0 要求 JDK 11 运行 Gradle。

配置方式：

# gradle.properties
org.gradle.java.home=/path/to/jdk-11

或设置环境变量：

export JAVA_HOME=/path/to/jdk-11

Variant API 稳定

新的 Variant API 现已稳定，推荐使用。

旧 API（废弃）：

android.applicationVariants.all { variant ->
    // 旧方式
}

新 API：

androidComponents {
    onVariants { variant ->
        // 新方式
    }
}

支持 Java 11 源代码

可以在项目中使用 Java 11 特性。

android {
    compileSdk = 30
    
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_11
        targetCompatibility = JavaVersion.VERSION_11
    }
    
    kotlinOptions {
        jvmTarget = "11"
    }
}

R8 缺失类警告

AGP 7.0 开始，R8 会更严格地警告缺失的类。

警告示例：

R8: Missing class: java.lang.instrument.ClassFileTransformer

处理方式：

添加到 proguard-rules.pro：

-dontwarn java.lang.instrument.ClassFileTransformer

或启用失败模式（推荐用于生产）：

# gradle.properties
android.r8.failOnMissingClasses=true

详细迁移步骤

更新 Gradle Wrapper：

./gradlew wrapper --gradle-version 7.2

更新 AGP 版本：

plugins {
    id("com.android.application") version "7.4.2"
    kotlin("android") version "1.9.0"
}

更新 JDK 到 11：

验证版本：

java -version  # 应显示 11.x

更新 Kotlin 到 1.5+：

AGP 7.0 要求 Kotlin 1.5.0 或更高版本。

plugins {
    kotlin("android") version "1.9.0"
}

启用非传递性 R 类（可选但推荐）：

# gradle.properties
android.nonTransitiveRClass=true

处理 Android Gradle Plugin 构建缓存移除：

以下属性已移除，如果还在使用需删除：

# ❌ 已移除
android.enableBuildCache
android.buildCacheDir

构建缓存现在完全由 Gradle build cache 处理。

依赖配置移除

某些已废弃的依赖配置被移除：

被移除：

• compile → 使用 implementation
• testCompile → 使用 testImplementation
• androidTestCompile → 使用 androidTestImplementation

---

通用迁移最佳实践

逐步升级：

• 不要跨多个大版本升级
• 例如：7.4 → 8.0 → 8.7 → 9.0

在独立分支测试：

• 创建新分支进行升级
• 完整测试后再合并
• 保留回滚选项

阅读发布说明：

• 查看每个版本的 Release Notes
• 关注破坏性变更章节
• 检查废弃 API 列表

更新所有依赖：

• 确保所有库兼容新 AGP 版本
• 更新第三方 Gradle 插件
• 检查插件最低 AGP 要求

使用自动化工具：

• Android Studio AGP Upgrade Assistant
• Lint 检查废弃 API
• 查看构建警告

分阶段迁移：

1. 第一阶段：修复破坏性变更
2. 第二阶段：处理废弃 API
3. 第三阶段：启用新功能

保留兼容性标志（临时）：

# gradle.properties
# 仅用于测试，不要长期依赖
android.builtInKotlin=false  # AGP 9.0+
# 这些标志会在后续版本移除

监控构建性能：

• 使用 Build Analyzer 分析构建时间
• 检查新版本是否影响性能
• 调整构建配置优化

完整测试：

• 运行所有单元测试
• 运行所有 instrumentation 测试
• 手动测试关键功能
• 在所有目标设备上测试