4. 常见错误信息解析

AGP 版本不匹配时，Gradle 同步或构建会抛出一堆红色日志。说实话，很多新手看到那一屏报错就慌了。别急，我来帮你拆解最常见的几种报错，教你一眼看出问题在哪。

4.1 「Minimum supported Gradle version is X.x」

这个报错太经典了。你升级了 AGP 到 8.x，结果 Gradle 还在 7.x 晃悠。Gradle 同步直接罢工。

FAILURE: Build failed with an exception.

* What went wrong:
The Android Gradle plugin requires Gradle 8.0 or higher.
Current version is 7.5.1.
Please fix the project's Gradle settings.

日志解读：

• Current version is 7.5.1 —— 当前 Gradle 版本号，一眼就能看到。
• requires Gradle 8.0 or higher —— AGP 的最低要求。说白了，AGP 和 Gradle 是绑定的，高版本 AGP 必须配高版本 Gradle。
• 原因：AGP 内部 API 变了，旧 Gradle 不识别新 AGP 的 DSL。

4.2 「Supports only Kotlin Gradle plugin version Y.y」

这个我项目中遇到过好几次。AGP 8.2 只支持 Kotlin 1.9.x，结果项目的 Kotlin 插件是 1.8.0。报错长这样：

ERROR: The Android Gradle plugin supports only Kotlin Gradle plugin version 1.9.0 and higher.
Project 'app' is using Kotlin plugin version 1.8.0.

日志含义：

• AGP 发布了新版本后，会废弃一些旧的 Kotlin 编译接口。版本差太多，AGP 直接拒绝干活。
• Kotlin 版本括号里写的是 1.9.0 and higher，并不是说必须正好 1.9.0，只要大于等于就行。

4.3 「Conflict with dependency 'com.android.support:appcompat'」

AGP 升级后，最头疼的其实是依赖冲突。尤其是从 support 库迁移到 AndroidX 时，或者多个子模块引了不同版本的同一个库。

ERROR: Conflict with dependency 'com.android.support:appcompat-v7' in project ':app'.
Resolved versions for app (28.0.0) and test app (26.1.0) differ.

日志解读：

• Resolved versions for app (28.0.0) and test app (26.1.0) differ —— 主模块和测试模块依赖的 appcompat 版本不一样，Gradle 不知道选哪个。
• 本质：Gradle 在 dependency resolution 时发现同一个 group 下不同版本，无法自动统一。
• 常见场景：某个第三方 SDK 强制依赖了旧版本，而你的项目用了新版本。

configurations.all {
    resolutionStrategy {
        force 'com.android.support:appcompat-v7:28.0.0'
    }
}
// 或排除某个传递依赖
implementation('com.example:sdk:1.0.0') {
    exclude group: 'com.android.support'
}

4.4 「Could not find com.android.tools.build:gradle:X.Y.Z」

有时候你会看到这个报错，同步直接挂掉：

Could not find com.android.tools.build:gradle:4.2.0.
Searched in the following locations:
  - https://dl.google.com/dl/android/maven2/com/android/tools/build/gradle/4.2.0/gradle-4.2.0.pom
  - https://repo1.maven.org/maven2/com/android/tools/build/gradle/4.2.0/gradle-4.2.0.pom
Required by:
  project :

日志含义：

• Gradle 找不到你声明的 AGP 版本。要么是你写错了版本号（比如 4.2.0 不存在），要么是你的仓库没配对。
• 注意 URL 前缀：dl.google.com/dl/android/maven2 是 Google Maven 仓库。如果它不存在，可能是 AGP 版本太老已被下架，或者你忘了加 google() 仓库。

4.5 AGP 与 AndroidX 迁移报错

当 AGP 升级到 8.x，但项目还没完全迁移到 AndroidX 时，你会看到类似的报错：

error: Attribute "android:name" in tag "activity" requires a valid reference.
or
** android:name cannot be empty **

这看起来不像版本冲突，但根源就是 android.enableJetifier=true 和 android.useAndroidX=true 设置不当。

日志解读：

• AGP 8.x 默认移除了对旧 support 库的编译支持。如果你还用的 support 库编译，但 Jetifier 没开，就会报这些奇怪的 attribute 错误。
• 现象：XML 里的 android:name 属性明明写对了，但 Gradle 说无效。
• 本质：support 库的 AAR 里引用了旧的 R 类或清单标记，新 AGP 无法处理。

android.useAndroidX=true
android.enableJetifier=true

4.6 遇到报错时的标准排查步骤

我个人习惯按照这个流程来，能省不少时间：