Android Gradle Plugin（AGP）在升级过程中经常伴随一系列依赖配置异常问题，尤其是在多模块项目或历史版本较久的工程中更为明显。常见表现包括编译失败、依赖冲突、找不到类、版本解析异常以及Sync卡死等问题。要稳定完成升级，需要从版本兼容、依赖链路、Gradle配置结构三个层面系统排查。
升级前的版本兼容性评估是最容易被忽视的环节。AGP版本与Gradle版本存在严格对应关系，例如AGP 7.x通常要求Gradle 7.x，而AGP 8.x则需要Gradle 8.x支持。如果直接修改插件版本而未同步升级Gradle Wrapper，就会出现“Could not find method”或构建脚本无法解析的问题。建议优先查看官方版本兼容表，再统一调整 gradle-wrapper.properties 中的 distributionUrl，避免出现半升级状态。
依赖冲突是升级后最常见的异常来源之一。尤其是在引入AndroidX迁移之后，不同库之间可能仍然依赖旧Support库，导致编译期出现 Duplicate class 或 Program type already present。此时需要通过 ./gradlew app:dependencies 命令分析依赖树，定位冲突来源。对于无法直接升级的三方库，可以通过 implementation 强制替换或使用 resolutionStrategy 进行版本统一管理，从根源上减少重复依赖加载。
Gradle 7+ 引入的 repositories 管理变化也会引发构建异常。部分项目仍然在 build.gradle 中混用 jcenter、mavenCentral 和私有仓库，但在新版本中 jcenter 已逐渐废弃，导致依赖解析失败或超时。统一仓库声明位置到 settings.gradle 中的 dependencyResolutionManagement 可以有效避免多模块仓库不一致问题，同时提升依赖解析稳定性。
插件版本不匹配同样会造成隐性错误。例如 kotlin-gradle-plugin 与 AGP 不一致时，可能出现 kapt 任务无法生成代码或 annotation processor 不执行的问题。建议在升级过程中保持 Kotlin、AGP、Gradle 三者同步升级，并参考官方推荐组合版本，而不是单独升级某一项组件。
在多模块项目中，buildSrc 或 Version Catalog 结构变化也容易导致配置失效。特别是从传统 ext 扩展迁移到 libs.versions.toml 时，如果版本声明遗漏或命名不一致，会直接导致模块无法识别依赖版本。排查时应重点检查 catalog 文件是否被正确引入，以及各模块是否引用统一版本管理体系。
Gradle Sync 卡住或超时问题往往与缓存或代理配置有关。升级后旧缓存可能与新版本构建逻辑冲突，可以通过清理 ~/.gradle/caches 和项目中的 .gradle 目录解决。同时检查 gradle.properties 中的 HTTP/HTTPS 代理设置，避免因仓库访问失败导致解析阻塞。
Annotation Processor 在 AGP 升级后行为变化也是常见坑点之一。尤其是从 apply plugin 方式迁移到 plugins DSL 后，部分 kapt 或 annotationProcessor 不再自动生效。需要确认是否启用了正确的 Java Toolchain，并检查 incremental annotation processing 是否被关闭或冲突。
Gradle Task 行为变化也可能引发构建异常。例如 assembleDebug 在新版本中任务依赖关系调整，某些自定义 task 如果依赖旧 API，会出现 Task not found 或 execution order 错乱的问题。建议统一迁移到 register 方式定义 task，并避免使用已废弃的 project.afterEvaluate 逻辑。
对于混合编译（Java + Kotlin）的项目，JVM target 不一致会导致 dex 或 class 兼容问题。在升级 AGP 后应统一设置 kotlinOptions { jvmTarget = "17" } 或与 Java compileOptions 保持一致，否则可能出现 NoSuchMethodError 或运行时崩溃。
升级过程中还需关注 AndroidManifest 合并规则变化。新版本 AGP 对 manifest merger 的策略更加严格，冲突属性不会自动覆盖，而是直接报错。通过 tools:replace 或显式声明 manifest placeholder 可以解决大多数冲突问题，但更推荐从依赖库层面修正重复声明。
在持续集成环境中，CI 构建失败往往比本地更难排查。原因通常是 Gradle Daemon 缓存差异或 JDK 版本不一致。确保 CI 使用与本地一致的 JDK（通常为 17 或 21）并关闭不必要的 daemon 可以提升构建稳定性。
系统化排查思路应优先确认版本链路，再检查依赖冲突，随后验证仓库配置，最后处理插件与任务兼容性问题。避免单点修复反复回归，才能保证升级后的工程长期稳定运行。
