本文详解 Android Studio 中 build.gradle 依赖配置的正确写法，重点解决因仓库声明冲突（如“prefer settings repositories”错误）和过时仓库（如 jcenter()）导致的构建失败问题，并提供兼容 Gradle 7.4+ 的标准化配置方案。
本文详解 android studio 中 `build.gradle` 依赖配置的正确写法，重点解决因仓库声明冲突（如“prefer settings repositories”错误）和过时仓库（如 `jcenter()`）导致的构建失败问题，并提供兼容 gradle 7.4+ 的标准化配置方案。
在 Android Studio 新项目中，构建失败（如 'app process Debug Resource' failure）往往并非代码问题，而是由 Gradle 配置不当引发——尤其是 build.gradle（Project 级）中仓库（repositories）声明方式与 Gradle 版本策略不兼容所致。自 Gradle 7.0 起，官方强制推行 settings repository 优先机制，即推荐将仓库统一声明在 settings.gradle 中，而非分散在 build.gradle 内。若仍在 build.gradle 中调用 google() 或 mavenCentral()，就会触发您遇到的报错：
“build was configured to prefer settings repositories but repository google was added by build file 'build.gradle':17”
这表示 Gradle 检测到项目启用了 settingsRepositories 模式，但您仍在 build.gradle 中手动添加了仓库，造成策略冲突。
✅ 正确做法是：双轨适配——既保持 build.gradle 的向后兼容性（尤其对旧插件），又遵循新规范。以下是经过验证的、适用于 Android Gradle Plugin (AGP) 7.4.2 的 Project 级 build.gradle 推荐配置：
// Project-level build.gradle
buildscript {
repositories {
google() // 必须保留，用于下载 AGP 插件
mavenCentral() // 替代已停用的 jcenter()（2021 年 2 月起只读，2023 年彻底关闭）
// jcenter() // ❌ 已废弃，建议移除或仅作临时兼容（加注释警告）
maven { url 'https://jitpack.io' } // 第三方开源库（如 GitHub 项目）常用
}
dependencies {
classpath 'com.android.tools.build:gradle:7.4.2'
classpath 'com.google.gms:google-services:4.3.15' // 如需 Firebase/GMS 服务
// 其他 classpath（如 Navigation Safe Args、Hilt）也在此添加
}
}
allprojects {
repositories {
google()
mavenCentral()
// jcenter() // ⚠️ 强烈建议删除；若必须保留，请明确注释“DEPRECATED”
maven { url 'https://jitpack.io' }
}
}
// 推荐添加 clean 任务，避免缓存污染
task clean(type: Delete) {
delete rootProject.buildDir
}? 关键注意事项：
- jcenter() 已正式退役：JFrog 于 2023 年 2 月关闭 jcenter.bintray.com，继续使用将导致依赖解析失败。请立即替换为 mavenCentral() 或对应厂商仓库（如 maven { url 'https://oss.sonatype.org/content/repositories/snapshots/' }）。
-
settings.gradle 优先级更高：若您使用的是 Gradle 7.2+，更规范的做法是将仓库声明迁移至 settings.gradle（如下），此时 build.gradle 中的 repositories 块应完全删除：
// settings.gradle dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { google() mavenCentral() maven { url 'https://jitpack.io' } } } - 版本对齐很重要：确保 com.android.tools.build:gradle:7.4.2 与 Gradle Wrapper 版本匹配（AGP 7.4.x 要求 Gradle 7.5+）。检查 gradle/wrapper/gradle-wrapper.properties 中 distributionUrl 是否为 gradle-7.5-bin.zip 或更高。
? 总结：构建失败常源于配置惯性而非技术门槛。摒弃 jcenter()、统一使用 mavenCentral() + google()、理解 settingsRepositories 机制，即可一劳永逸规避此类错误。新项目强烈建议直接采用 settings.gradle 声明仓库，让 build.gradle 专注逻辑而非基础设施。
