本文详解 Android Studio 中 build.gradle 仓库配置冲突的成因与解决方案，重点解决因混合使用 settings.gradle 仓库偏好与 build.gradle 手动添加 google() 导致的构建失败问题，并提供兼容性强、符合 Gradle 7.5+ 和 AGP 7.4+ 最佳实践的配置模板。
本文详解 android studio 中 `build.gradle` 仓库配置冲突的成因与解决方案，重点解决因混合使用 `settings.gradle` 仓库偏好与 `build.gradle` 手动添加 `google()` 导致的构建失败问题，并提供兼容性强、符合 gradle 7.5+ 和 agp 7.4+ 最佳实践的配置模板。
在 Android Studio 新项目中，初学者常通过直接修改项目级 build.gradle（即 build.gradle 文件，位于项目根目录）来添加仓库或依赖，但自 Android Gradle Plugin (AGP) 7.0+ 起，Gradle 强制推行仓库声明集中化管理——推荐在 settings.gradle 中统一配置 dependencyResolutionManagement，而非在 buildscript 或 allprojects 块中重复声明 google()、mavenCentral() 等仓库。你遇到的错误：
“build was configured to prefer settings repositories but repository google was added by build file 'build.gradle':17”
正是这一机制触发的安全限制：当 settings.gradle 启用了 repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)（默认行为），而你在 build.gradle 中又显式调用 google()，Gradle 就会拒绝构建，防止仓库来源混乱和潜在的安全/一致性风险。
✅ 正确做法是 移除 build.gradle 中所有 repositories 块，将仓库统一交由 settings.gradle 管理；仅保留 buildscript.dependencies 中必需的 classpath 依赖（如 AGP 和 Google Services 插件）。以下是推荐配置方案：
1. 修改 settings.gradle（推荐方式，符合现代 Gradle 规范）：
dependencyResolutionManagement {
repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)
repositories {
google()
mavenCentral()
// jcenter() 已于 2021 年底停服，强烈建议移除
maven { url 'https://jitpack.io' }
}
}
rootProject.name = "YourAppName"
include ':app'
2. 精简项目级 build.gradle（仅保留必要内容）：
// ✅ 移除了 buildscript.repositories 和 allprojects.repositories
buildscript {
dependencies {
classpath 'com.android.tools.build:gradle:7.4.2'
classpath 'com.google.gms:google-services:4.3.15' // 如需 Firebase/GMS
}
}
// 可选：保留 clean 任务（非必需，但无害）
task clean(type: Delete) {
delete rootProject.buildDir
}
⚠️ 注意事项：
- jcenter() 已正式关闭，继续使用将导致依赖解析失败，请立即替换为 mavenCentral() 或对应替代源；
- google() 仓库必须在 settings.gradle 的 repositories 块中声明，不可出现在 build.gradle 内；
- 若项目使用 Kotlin DSL，对应文件为 settings.gradle.kts，语法略有差异（如 repositories { google(); mavenCentral() }）；
- 修改后务必点击 File → Sync Project with Gradle Files，避免缓存导致配置未生效。
总结：Gradle 的仓库管理模式已从“分散声明”转向“集中管控”。遵循 settings.gradle 统一声明 + build.gradle 专注依赖声明的原则，不仅能解决当前报错，更能提升项目可维护性与构建稳定性。
