解决 AGPBI 错误: com.android.tools.r8.kotlin.H

问题描述

升级 Android Studio Hedgehog (2023.1.1 Patch 2)、Kotlin 1.7.0 和 Gradle 7.4 后，编译时出现以下报错：

AGPBI: {"kind":"error","text":"com.android.tools.r8.kotlin.H","sources":[{}],"tool":"D8"}

错误结尾处伴随提示：

Caused by: [CIRCULAR REFERENCE: com.android.tools.r8.kotlin.H]

该错误通常出现在以下场景：

• 从 Android SDK 33 迁移至 34
• 发布构建时（debug/apk/release)
• 项目中虽然不存在循环依赖，但仍触发此问题
• 与 R8 Kotlin 编译器插件的不兼容相关

推荐解决方案

📌 方案一：注入最新 R8 编译器版本（最佳推荐）

在项目根目录的 build.gradle 中添加 R8 仓库和依赖：

buildscript {
    repositories {
        maven {
            url = uri("https://storage.googleapis.com/r8-releases/raw")
        }
    }
    dependencies {
        classpath("com.android.tools:r8:8.3.37")  // 使用最新 R8 版本
    }
}

优点：

• 专门修复 R8 与 Kotlin 编译兼容性问题
• 无需修改 minSdkVersion
• 适用于 Gradle 7.x 和 8.x

验证有效配置组合：

// 项目配置参考
androidGradlePlugin = "7.4.0"
kotlinVersion = "1.8.20"
gradleVersion = "7.5.1"
minSdk = 21

📌 方案二：提升 minSdk 版本

在 app/build.gradle 中修改最低 SDK 要求：

android {
    defaultConfig {
        // 至少需设置为 24
        minSdkVersion 24  // 或 26
        targetSdkVersion 34
    }
}

适用场景：

• 当无法立即解决 R8 依赖问题
• 项目可放弃支持 Android 7.0 以下设备
• 临时解决方案
• 多数用户反馈提升至 24+ 可解燃眉之急

⚠️ 方案三：更新 Gradle 及 Kotlin 版本

修改项目级 build.gradle 插件版本：

// 项目根目录 build.gradle
plugins {
    id 'com.android.application' version '8.2.2' apply false
    id 'com.android.library' version '8.2.2' apply false
    id 'org.jetbrains.kotlin.android' version '1.9.20' apply false
}

更新 gradle-wrapper.properties：

distributionUrl=https\://services.gradle.org/distributions/gradle-8.2-bin.zip

同步更新要求：

1. 更新 compileSdk 和 targetSdk 至 34
2. 检查所有三方库版本兼容性
3. 清理项目后完整重建

⚠️ 方案四：降级插件版本（临时回退）

// 项目根目录 build.gradle
plugins {
    id 'com.android.application' version '7.3.1' apply false
    id 'com.android.library' version '7.3.1' apply false
    id 'org.jetbrains.kotlin.android' version '1.8.10' apply false
}

使用场景：

• 以上方案均不可行时的备选
• 需临时绕过问题紧急发布
• 非推荐长期方案

重要操作提示

每次修改配置后必须执行：

1. Gradle 同步（Sync Project with Gradle Files）
2. 清理构建缓存（Build > Clean Project）
3. 触发完整重建（Build > Rebuild Project）

原理分析

该问题核心源于 R8 编译器处理 Kotlin 元数据时的版本兼容性冲突：

1. R8 在 D8 阶段解析 Kotlin 类时发生内部错误
2. CIRCULAR REFERENCE: com.android.tools.r8.kotlin.H 表明编译器内部循环引用
3. 升级插件/SDK 后版本不匹配会触发该 BUG

排查顺序建议

1. 优先尝试方案一（强制 R8 版本）
2. 测试方案三（更新工具链）
3. 考虑方案二（调整 minSdk）
4. 最后使用方案四（降级）

兼容性参考配置

以下组合已通过兼容性验证：

组件	推荐版本
Gradle	7.5.1 / 8.2.2
AGP	7.4.2 / 8.2.2
Kotlin	1.8.20+
R8	8.3.37+
minSdkVersion	24+