修复 Gradle ArtifactResolveException: 解决依赖解析失败

2025-04-24 11:39:21

搞定 Gradle ArtifactResolveException: 解决 :app:debugRuntimeClasspath 依赖解析失败

开发安卓应用时，碰上 Gradle 构建错误是家常便饭。其中，ArtifactResolveException: Could not resolve all files for configuration ':app:debugRuntimeClasspath' 这个报错就挺让人头疼的。它明确告诉你：Gradle 在尝试为你应用的 debug 构建类型准备运行时所需的库（也就是依赖）时，有些文件找不着或者下载失败了。

你可能正在兴致勃勃地做一个 Spotify 克隆 App，就像提问者那样，结果一点运行按钮，App 没跑起来，反而在 Build 输出里看到了这个糟心的错误。别慌，这通常不是什么大问题，咱们一步步来排查。

这错误是咋回事？

简单说，Gradle 构建系统就像个项目经理，它需要根据你的 build.gradle 文件里的指示，去各个仓库（比如 google(), mavenCentral()）把项目依赖的第三方库（artifacts/files）都找齐了，才能把你的 App 打包出来。

debugRuntimeClasspath 指的就是专门为 debug 构建类型（通常就是我们开发时用的类型）在运行时（Runtime）需要的所有依赖项（Classpath）。当 Gradle 说 Could not resolve all files 时，意思就是它在这个环节里，没能把列表上所有的库都下载到本地或者找到对应的文件。

常见的原因有这么几种：

网络连接问题 ：最直观的原因，电脑没联网，或者网络不稳定，导致 Gradle 访问不了远程仓库（比如 Maven Central, Google Maven）。
仓库配置错误 ：build.gradle 或 settings.gradle 文件里声明的仓库地址不对，或者有些库所在的私有仓库、特定仓库（像 JitPack）没加进去。
依赖声明错误 ：
- 库的坐标写错了（groupId:artifactId:version 有拼写错误）。
- 指定的版本号不存在。
- 库已经被作者从仓库移除了。
- 依赖之间存在版本冲突，Gradle 无法自动解决。
Gradle 缓存损坏 ：Gradle 为了加快构建速度，会缓存下载的依赖和构建信息。有时候缓存文件出错了，就会导致解析失败。
Gradle 版本或插件不兼容 ：Android Gradle 插件（AGP）版本、Gradle 版本、Kotlin 插件版本之间可能存在兼容性要求，版本没对齐也可能出问题。
Hilt/Dagger 配置问题 ：从提问者的 build.gradle 看，项目用了 Hilt。Hilt 的配置稍微复杂点，包括插件应用、依赖声明（implementation 和 kapt）、项目级 classpath 依赖，任何一环出问题都可能影响依赖解析。

怎么解决？试试这些法子

下面列出一些常见的解决步骤，你可以按顺序尝试。

1. 检查网络连接和仓库配置

这是最基本但也容易被忽略的一步。

确认网络 ：确保你的开发机器网络通畅，能正常访问外网。如果你在公司内网，检查下是否有代理限制，或者是否需要配置特定的公司 Maven 仓库镜像。

检查仓库声明 ：

打开你项目根目录下的 settings.gradle（或 settings.gradle.kts）文件。确保 dependencyResolutionManagement -> repositories 块里包含了你需要的所有仓库。通常至少要有 google() 和 mavenCentral()。如果你用了像 JitPack 这样的服务，别忘了加上 maven { url = 'https://jitpack.io' }。

// settings.gradle
pluginManagement {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
        // 如果有插件在 JitPack 或其他地方
        maven { url 'https://jitpack.io' }
    }
}
dependencyResolutionManagement {
    // RepositoriesMode.FAIL_ON_PROJECT_REPOS 是推荐的做法，强制在 settings.gradle 中声明仓库
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        // 如果项目依赖在 JitPack 或其他地方
        maven { url 'https://jitpack.io' }
        // 如果有公司内部私服
        // maven { url 'https://your.company.repo/repository/maven-public/' }
    }
}

检查项目根目录的 build.gradle 文件（Project Level）。buildscript -> repositories 块是用来解析 Gradle 插件本身的仓库，也要确保 google() 和 mavenCentral() 等是存在的。

// build.gradle (Project Level)
buildscript {
    repositories {
        google()
        mavenCentral()
    }
    dependencies {
        // 确保这里的插件版本号是有效的
        classpath "com.android.tools.build:gradle:7.2.1" // 示例版本
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:1.7.0" // 示例版本
        classpath 'com.google.gms:google-services:4.3.13' // 提问者用的版本
        // 如果 Hilt 插件在这里声明（较新方式是在 plugins {} 块里）
        // classpath "com.google.dagger:hilt-android-gradle-plugin:2.38.1" // 示例版本
    }
}

// 注意：新版本的 Gradle 推荐在 settings.gradle 的 pluginManagement 中管理插件仓库和版本

安全建议 ：
- 避免在 allprojects 或 subprojects 块里配置 repositories，dependencyResolutionManagement 是更现代、更推荐的方式。
- 如果使用公司代理，需要在用户主目录下的 .gradle/gradle.properties 文件中配置代理信息 (systemProp.http.proxyHost, systemProp.http.proxyPort, systemProp.https.proxyHost, systemProp.https.proxyPort 等)。

2. 清理项目和 Gradle 缓存

缓存损坏是导致这类问题的常见元凶。可以试试“简单粗暴”但有效的方法：

Android Studio 菜单 ：
1. 点击 Build -> Clean Project。
2. 点击 File -> Invalidate Caches / Restart...。在弹出的对话框里，可以勾选 Clear file system cache and Local History 和 Clear VCS Log caches and indexes，然后点击 Invalidate and Restart。
Gradle 命令行 ：
在 Android Studio 的 Terminal 窗口或者系统命令行里，进入项目根目录，执行：
- 在 Windows 上： .\gradlew clean build --refresh-dependencies
- 在 macOS 或 Linux 上： sh gradlew clean build --refresh-dependencies
clean 任务会删除 build 目录。build 会重新构建。--refresh-dependencies 参数会强制 Gradle 忽略缓存，重新检查并下载所有依赖。
进阶：手动删除缓存 （谨慎操作）：
如果上面的方法还不行，可以考虑手动删除 Gradle 的全局缓存。
1. 关闭 Android Studio。
2. 找到 Gradle 用户主目录，通常是：
  - Windows: C:\Users\<你的用户名>\.gradle
  - macOS/Linux: /Users/<你的用户名>/.gradle 或 $HOME/.gradle
3. 删除这个目录下的 caches 文件夹。
4. 同时也可以考虑删除项目根目录下的 .gradle 文件夹和 .idea 文件夹（删除 .idea 会重置你的项目配置，Android Studio 重新打开时会重建）。
5. 重新打开 Android Studio，它会重新下载所有依赖和 Gradle Wrapper，这个过程会比较慢。

3. 仔细检查依赖声明

回到 app/build.gradle（Module: app），逐行检查 dependencies 块里的每一项：

拼写和格式 ：groupId:artifactId:version 这三段，用冒号分隔，是不是都写对了？大小写敏感。
版本号有效性 ：你指定的版本号真的存在吗？可以去 Maven Central (search.maven.org) 或 Google Maven Repository (maven.google.com) 搜一下对应的库，看看有哪些可用的版本。
版本冲突 ：项目里不同的库可能间接依赖了同一个库的不同版本，比如你的 App 直接依赖 library-A:1.0，同时依赖了 library-B:2.0，而 library-B 内部又依赖了 library-A:0.9。Gradle 会尝试解决这种冲突（通常选高版本），但有时会失败，或者选了一个不兼容的版本。
- 检查提问者的 build.gradle :
  - Hilt 版本混用 ：这是一个非常可疑的地方！你同时声明了：
    - implementation "com.google.dagger:hilt-android:2.28-alpha"
    - implementation "androidx.hilt:hilt-lifecycle-viewmodel:1.0.0-alpha03"
    - implementation "com.google.dagger:hilt-android:2.38.1"
    - kapt("com.google.dagger:hilt-android-compiler:2.38.1")
      问题：2.28-alpha 和 2.38.1 是不同版本的 Hilt Android 运行时。androidx.hilt:hilt-lifecycle-viewmodel 是非常早期的 Hilt 扩展库，现在已经被整合或废弃。你需要统一 Hilt 相关依赖的版本！
      建议修改 ：
    1. 移除 implementation "com.google.dagger:hilt-android:2.28-alpha"。
    2. 移除 implementation "androidx.hilt:hilt-lifecycle-viewmodel:1.0.0-alpha03" (ViewModel 的 Hilt 支持现在是内置的，或者通过 hilt-navigation-compose 等库提供)。
    3. 确保 implementation "com.google.dagger:hilt-android:2.38.1" 和 kapt("com.google.dagger:hilt-android-compiler:2.38.1") 的版本号完全一致。如果用了 Hilt 的 Gradle 插件，插件版本也要和这两个依赖协调。
  - Lifecycle 版本 : 你用了多个 Lifecycle 库，版本基本都是 2.4.1，但有一个 implementation "androidx.lifecycle:lifecycle-extensions:2.2.0"。lifecycle-extensions 已经被废弃了，它的功能（如 ViewModelProviders.of) 已经被 androidx.activity:activity-ktx 或 androidx.fragment:fragment-ktx 里的 viewModels() 委托等替代。建议移除 lifecycle-extensions。
  - Firebase :
    - 你同时依赖了 firebase-firestore 和 firebase-firestore-ktx，这通常是没问题的，ktx 版本提供了 Kotlin 扩展。
    - 版本号 (24.1.2 和 24.2.0) 有微小差异，虽然 Firebase 通常能处理，但使用 Firebase BoM (Bill of Materials) 是更好的做法，可以保证所有 Firebase 库版本兼容。
  - ExoPlayer : 2.18.0，这个版本是存在的。使用 api 还是 implementation 取决于你是否想让你的 App 模块暴露 ExoPlayer 的 API 给其他模块。一般用 implementation 更安全，封装性更好。如果你的 App 就是最终产品，用哪个差别不大。
进阶：查看依赖树
如果怀疑是传递性依赖或版本冲突，可以在命令行运行：
.\gradlew :app:dependencies --configuration debugRuntimeClasspath (Windows)
sh gradlew :app:dependencies --configuration debugRuntimeClasspath (macOS/Linux)

这个命令会打印出 app 模块在 debugRuntimeClasspath 配置下的完整依赖树，包括每个库的来源、请求的版本和最终解析出的版本。你可以从中找到标记有冲突 (-> 指向不同版本) 或失败 (FAILED) 的地方。

4. 同步 Gradle 文件

在 Android Studio 修改了任何 build.gradle 或 settings.gradle 文件后，IDE 顶部通常会显示一个黄条提示 "Gradle files have changed since last project sync..."。务必点击 "Sync Now"。或者手动点击工具栏上的小象图标（Sync Project with Gradle Files）。

5. 更新 Gradle 和相关插件

确保 Android Gradle 插件（AGP）、Gradle 本身以及 Kotlin 插件版本是相互兼容的。

AGP 版本 ：在项目级 build.gradle 的 plugins 块 (或者 buildscript -> dependencies -> classpath "com.android.tools.build:gradle:...")。
Gradle 版本 ：在 gradle/wrapper/gradle-wrapper.properties 文件里的 distributionUrl 指定。
Kotlin 插件版本 ：在项目级 build.gradle 的 plugins 块 (或者 buildscript -> dependencies -> classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:...")。

查阅 Android Gradle 插件版本说明来确定 AGP 版本对应的推荐 Gradle 版本和兼容的 Kotlin 插件版本。例如，AGP 7.2.x 通常需要 Gradle 7.3.3+，并与 Kotlin 1.6.x 或 1.7.x 兼容。你的配置看起来（AGP 7.2.1, Kotlin 1.7.0）基本匹配，但务必确认 Gradle Wrapper 版本是否也匹配（在 gradle-wrapper.properties 里看）。

如果需要更新，修改对应文件的版本号，然后进行 Gradle Sync。

6. 仔细检查 Hilt/Dagger 配置（重点针对提问者）

除了依赖版本统一（如第 3 点所述），Hilt 配置还涉及：

应用 Hilt 插件 ：
确保在 app 模块的 build.gradle 文件顶部 plugins 块中应用了 Hilt 插件：

plugins {
    // ... 其他插件
    id 'kotlin-kapt'
    id 'dagger.hilt.android.plugin' // 或者 'com.google.dagger.hilt.android'，取决于版本
}

你好像没加 dagger.hilt.android.plugin 这个插件？ 这是必需的！
(你的代码里有 implementation "com.google.dagger:hilt-android:2.38.1" 和 kapt "com.google.dagger:hilt-android-compiler:2.38.1", 但缺少 Hilt Gradle 插件的应用)

修正你的 app/build.gradle 的 plugins 部分:

plugins {
    id 'com.android.application'
    id 'org.jetbrains.kotlin.android' // id 'kotlin-android' 是旧写法
    // kapt 插件通常需要放在 hilt 插件之前或之后，看文档建议，放之后一般没问题
    id 'kotlin-kapt'
    id 'com.google.dagger.hilt.android' // ** 添加这一行 ** 
    id 'com.google.gms.google-services'
    // 移除冗余的 'kotlin-android' 和 'kotlin-kapt'
}

项目级 classpath 依赖 (对于较旧的 Hilt 设置方式可能需要):
确保项目级 build.gradle 文件中有 Hilt Gradle 插件的 classpath 依赖 (如果不是在 settings.gradle 中通过 pluginManagement 管理):
```
// build.gradle (Project Level)
buildscript {
    // ... repositories ...
    dependencies {
        // ... other classpaths ...
        classpath "com.google.dagger:hilt-android-gradle-plugin:2.38.1" // **版本要和依赖库一致** 
    }
}
```
你的项目级 build.gradle 里似乎也没有这个 classpath 依赖。
注解处理器 (kapt) : 你已经正确添加了 kapt("com.google.dagger:hilt-android-compiler:...")，并应用了 kotlin-kapt 插件。

总结 Hilt 的修改建议 ：

统一 app/build.gradle 中 implementation 和 kapt 的 Hilt 依赖版本为 2.38.1。
移除旧的、冲突的 Hilt 依赖（2.28-alpha, androidx.hilt:hilt-lifecycle-viewmodel）。
在 app/build.gradle 的 plugins 块添加 id 'com.google.dagger.hilt.android'。
如果你的 AGP 和 Gradle 版本组合还需要，在项目级 build.gradle 的 buildscript -> dependencies 添加 classpath "com.google.dagger:hilt-android-gradle-plugin:2.38.1"。（对于 AGP 7.0+ 和较新 Gradle，通常仅在 app 的 plugins 块应用即可）。

7. 检查 Firebase 配置

Firebase 也需要正确的插件配置。

应用 Google Services 插件 ：确保在 app 模块的 build.gradle 文件末尾（或者根据你的 Gradle 版本，可能在 plugins 块）应用了插件：apply plugin: 'com.google.gms.google-services' (如果不在 plugins 块的话)。你的 plugins 块里有 id 'com.google.gms.google-services'，这是正确的。
项目级 classpath 依赖 ：确保项目级 build.gradle 有 classpath 'com.google.gms:google-services:...' 依赖。你的文件里是 4.3.13，这版本没问题。
google-services.json 文件 ：确认你已经从 Firebase 控制台下载了 google-services.json 文件，并正确放置在 app 模块的根目录下。

8. 使用 Firebase BoM 管理 Firebase 依赖

为了避免 Firebase 库之间的版本不兼容问题，推荐使用 Firebase Bill of Materials (BoM)。

修改你的 app/build.gradle 的 dependencies 块：

dependencies {
    // ... 其他依赖 ...

    // Import the Firebase BoM
    implementation platform('com.google.firebase:firebase-bom:30.3.1') // 使用最新的 BoM 版本

    // Declare the Firebase dependencies without versions
    implementation 'com.google.firebase:firebase-firestore-ktx'
    implementation 'com.google.firebase:firebase-storage-ktx'
    // 如果还需要非 KTX 版本 (通常不需要和 KTX 一起用)
    // implementation 'com.google.firebase:firebase-firestore'

    // ... 其他依赖，比如 Coroutines Play Services ...
    implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-play-services:1.1.1' // 注意：这个库版本也可能需要更新以兼容最新的 Play Services 或 Firebase 库

    // ... 其他依赖 ...
}

引入 BoM 后，你就不需要在每个 Firebase 库后面指定版本了，BoM 会自动管理这些版本，确保它们相互兼容。

9. 强制特定依赖版本（不到万不得已不推荐）

如果通过 gradle dependencies 发现确实是某个传递性依赖导致了无法解决的冲突，可以尝试强制指定一个版本。但这可能引入运行时问题，要小心使用。

// app/build.gradle
android {
    // ...
}

configurations.all {
    resolutionStrategy {
        // 强制指定某个库的版本
        force 'com.example.problematic:library:1.2.3'

        // 示例：如果androidx.core 有冲突
        // force 'androidx.core:core-ktx:1.7.0'
    }
}

dependencies {
    // ...
}

把 'com.example.problematic:library:1.2.3' 替换成你确定有问题的库及其你想强制使用的版本号。

遇到 ArtifactResolveException，尤其是在配置比较复杂的项目（比如用了 Hilt、Firebase 等），问题往往出在依赖声明、版本冲突或 Hilt/插件配置上。根据提问者提供的信息，Hilt 的版本混用和配置缺失看起来是最大的嫌疑 。按上面的步骤逐一排查，特别是 Hilt 部分的修改，应该能帮你定位并解决问题。