本文详解如何正确配置 android studio 的 build.gradle 文件，解决因混合使用 settings.gradle 仓库声明与 build.gradle 中手动添加仓库（如 google()）导致的构建失败问题，并提供兼容性强、符合现代 gradle 最佳实践的依赖管理方案。
本文详解如何正确配置 android studio 的 build.gradle 文件，解决因混合使用 settings.gradle 仓库声明与 build.gradle 中手动添加仓库（如 google()）导致的构建失败问题，并提供兼容性强、符合现代 gradle 最佳实践的依赖管理方案。
在 Android Studio 新项目中，尤其是使用较新版本（如 Giraffe 或 Hedgehog）时，Gradle 构建系统默认启用 settings repository 首选模式（configuration-cache 和 pluginManagement 驱动的仓库声明）。此时若仍在 build.gradle（项目级）中显式调用 google()、jcenter() 等仓库方法，就会触发如下典型错误：
Build was configured to prefer settings repositories but repository 'google' was added by build file 'build.gradle':17
该错误本质是 Gradle 的仓库声明策略冲突：新版 Android Gradle Plugin（AGP ≥ 7.0）要求统一通过 settings.gradle（或 settings.gradle.kts）声明所有仓库，而不再推荐/允许在 buildscript { repositories { ... } } 或 allprojects { repositories { ... } } 中重复添加。
✅ 正确做法（推荐，符合官方最佳实践）：
- 删除 build.gradle 中所有 repositories 块（包括 buildscript.repositories 和 allprojects.repositories）；
- 统一在 settings.gradle 中声明仓库（Groovy）：
// settings.gradle
pluginManagement {
repositories {
google()
mavenCentral()
gradlePluginPortal()
// 如需 JitPack，可保留（但注意 jcenter 已停用）
maven { url 'https://jitpack.io' }
}
}
dependencyResolutionManagement {
repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
repositories {
google()
mavenCentral()
maven { url 'https://jitpack.io' }
// ⚠️ 移除 jcenter() —— 官方已于 2021 年 3 月关闭服务，继续使用将导致解析失败
}
}
rootProject.name = "MyApp"
include ':app'- 确保 build.gradle（项目级）仅保留必要配置：
// build.gradle（项目根目录，仅保留 buildscript classpath）
buildscript {
dependencies {
classpath 'com.android.tools.build:gradle:7.4.2'
classpath 'com.google.gms:google-services:4.3.15' // 如集成 Firebase
// 其他插件 classpath（如 kotlin-gradle-plugin）也应在此声明
}
}
// ✅ 删除整个 buildscript.repositories 和 allprojects.repositories 块！? 关键注意事项：
- jcenter() 已于 2021 年正式退役，强制移除，否则构建会失败或拉取不到依赖；
- repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) 是安全兜底机制，可防止子模块误声明仓库；
- 若项目含 Kotlin，还需在 pluginManagement 中添加 mavenCentral() 并确保 kotlin-gradle-plugin 版本与 Kotlin 编译器匹配；
- 清理缓存后重试：执行 ./gradlew clean 或在 Android Studio 中点击 File → Invalidate Caches and Restart → Invalidate and Restart。
? 补充：如需全局清理任务，可在 build.gradle 中保留（非必需，但便于开发）：
task clean(type: Delete) {
delete rootProject.buildDir
}遵循以上结构，即可彻底规避“repository added by build file”类错误，构建稳定、可维护、符合 Android 官方演进方向的 Gradle 项目。
