升级Android Studio后报:app:debugRuntimeClasspath解析失败

这个报错本质是Gradle无法拉取/识别运行时需要的依赖文件，切换离线模式无效是因为离线模式只会读取本地已缓存的依赖，本地没有对应缓存时自然无法解决问题，按以下步骤排查修复：

1. 先对齐AGP和Gradle版本 #

升级Android Studio后最常见的问题就是Android Gradle Plugin（AGP）和Gradle版本不匹配，两者必须严格对应，常见版本对应关系：

• AGP 8.2.x 适配 Gradle 8.2.x
• AGP 8.3.x 适配 Gradle 8.4.x
• AGP 8.4.x 适配 Gradle 8.6.x
• AGP 8.5.x 适配 Gradle 8.7.x
  修改位置：
• AGP版本：项目根目录build.gradle的dependencies块，或者使用版本目录的话在gradle/libs.versions.toml里修改
• Gradle版本：gradle/wrapper/gradle-wrapper.properties文件内的distributionUrl字段，替换为对应版本的下载地址

2. 修正仓库配置 #

新版AGP要求所有仓库必须统一在项目根目录的settings.gradle内配置，不要在模块级或旧的根build.gradle里配置仓库，标准配置参考：

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google() // 必须放在首位，Android官方依赖优先从谷歌源拉取
        mavenCentral()
        // 第三方源比如JitPack放在后面即可
        // maven { url 'https://jitpack.io' }
    }
}

注意：必须移除配置里的jcenter()，JCenter已经停止服务，配置后会导致依赖解析超时或失败

3. 清理旧版本缓存后重新同步 #

旧版本残留的构建缓存会和新版Gradle/AGP冲突，按顺序操作：

• 确认关闭Gradle离线模式：打开Settings > Build, Execution, Deployment > Gradle，取消勾选Offline work
• 点击菜单栏File > Invalidate Caches...，勾选所有可选项后点击Invalidate and Restart等待IDE重启
• 重启后在项目根目录执行终端命令清理构建缓存：
  • Windows：gradlew cleanBuildCache
  • Mac/Linux：./gradlew cleanBuildCache
• 点击工具栏的Sync Project with Gradle Files按钮重新同步项目

4. 残留问题排查 #

如果以上操作后还是报错，展开报错信息的折叠项，找到具体解析失败的依赖针对性处理：

• 若为AndroidX/Support库依赖失败：检查gradle.properties中是否配置了android.useAndroidX=true、android.enableJetifier=true
• 若为第三方开源库失败：确认该库已经迁移出JCenter，且兼容当前使用的AGP版本
• 若为公司私有依赖失败：核对settings.gradle中私有Maven源的地址、鉴权配置，同时检查IDE的HTTP代理配置是否因为升级被重置

内容的提问来源于stack exchange，提问作者ardabzlk