如果你最近用 Gradle 构建 Android 项目时被org.gradle.api.InvalidUserCodeException: Build was configured to prefer settings repositories over project repositories...这种报错拦住先别急着把~/.gradle目录整个删掉。这个报错不是环境坏了也不是依赖下载失败而是你的工程里同时存在两套依赖仓库配置规则Gradle 在执行时发现它们冲突了。我会把原理、三种仓库模式的区别以及最直接的解决方案完整讲一遍适合正在被 Gradle 仓库配置折磨的新手也适合要处理 Flutter 混合工程和团队构建规范的老手。1. 先搞懂这个报错到底在说什么1.1 报错常见触发场景完整的报错信息一般长这样org.gradle.api.InvalidUserCodeException: Build was configured to prefer settings repositories over project repositories but repository MavenRepo was added by build file app/build.gradle它并不是工程文件损坏也不是网络问题而是 Gradle 在告诉你项目根目录下的settings.gradle已经规定所有依赖仓库统一放在 settings 里管理但某个模块的build.gradle文件里仍然出现了repositories声明。这两种配置方式打架了。最容易踩中的场景有三个。第一个是 Android Studio 新建项目模板从某个版本开始默认在settings.gradle中写入dependencyResolutionManagement块并设置RepositoriesMode.FAIL_ON_PROJECT_REPOS。如果你照旧在app/build.gradle里添加自定义仓库比如 JitPack、阿里云镜像、公司私有 Nexus构建立刻报错。第二个是 Flutter 工程。Flutter 生成的 android 目录同样带上了这套配置但很多 Flutter 插件或者你自己写的原生 module还在沿用旧习惯在build.gradle里声明仓库。于是执行flutter run或flutter build apk时这个错误就冒出来了。第三个是“拿来主义”工程。你从网上拉了一个项目别人把仓库写在了子模块里而你的 Gradle 版本比他的新。Gradle 从 6.8 开始引入dependencyResolutionManagement之后仓库配置策略的冲突会随着版本升级逐渐从警告变成硬失败。这个报错频繁出现恰恰说明大家还没有跟上 Gradle 集中管理依赖仓库的思路变化。1.2 为什么 Gradle 要把仓库集中到 settings早期 Gradle 项目里每个模块都可以在build.gradle里写自己的repositories。模块少的时候没问题模块一多就混乱了A 模块用了google()B 模块忘了加构建时依赖解析失败同一个仓库地址在不同的build.gradle里写了三次后续如果要切换镜像源得把所有文件都翻一遍。为了解决这个问题Gradle 6.8 开始支持在settings.gradle里统一声明仓库这就是dependencyResolutionManagement。settings 文件在构建一开始就会被解析它声明的仓库对全项目所有模块生效。这样仓库地址就变成单一来源团队再做镜像切换、私有仓库治理时只需要动一个文件。对于大型 Android 工程、Flutter 混合工程来说这种中心化配置的价值非常大。不过 Gradle 也得照顾老项目所以它提供了三种模式让迁移不是一刀切。报错的根源就是你的项目处于“强制统一”模式下但工程里还有旧式声明。2. repositoriesMode 三种模式怎么选2.1 三种模式行为对比dependencyResolutionManagement里的repositoriesMode其实就是一个门禁开关决定项目模块里的仓库声明到底还算不算数。三种模式的区别如下模式声明方式行为表现适用场景PREFER_PROJECTrepositoriesMode.set(RepositoriesMode.PREFER_PROJECT)优先使用模块build.gradle里的仓库settings 中的仓库作为兜底老项目迁移到新 Gradle 的过渡期兼容旧代码PREFER_SETTINGSrepositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)优先使用 settings 中的统一仓库模块里的仓库声明如果和 settings 不一致会被忽略并出现警告想逐步统一但希望降低改动量FAIL_ON_PROJECT_REPOSrepositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)模块的build.gradle里只要出现repositories直接抛InvalidUserCodeException构建失败Android Studio 新项目模板默认值适合新建工程强制规范严格意义上RepositoriesMode是 Gradle 6.8 之后随着dependencyResolutionManagement一起引入的。你可以把它理解成一扇门PREFER_SETTINGS和FAIL_ON_PROJECT_REPOS都表示“我要求集中管理”区别只在违规时是警告还是直接失败。而PREFER_PROJECT基本等于门禁关闭保留旧行为。2.2 触发报错的三种常见姿势第一种在app/build.gradle或某个 module 的build.gradle里直接添加仓库repositories { mavenCentral() maven { url https://jitpack.io } }如果settings.gradle是FAIL_ON_PROJECT_REPOS这里就炸了。第二种在写自定义 Gradle 插件或buildSrc时尝试在build.gradle里配置插件依赖仓库。虽然插件仓库通常应该放在settings.gradle的pluginManagement.repositories里但有些教程把两件事混在一起也会踩中。第三种某些第三方 SDK 官方文档仍然要求你在工程级build.gradle的allprojects.repositories中添加它们的仓库地址。这种老式文档和新的dependencyResolutionManagement直接冲突尤其是把旧的maven { url ... }写在根工程里构建时照样报错。3. 解决方案实操四种处理路径3.1 方案一把仓库统一挪到 settings.gradle最推荐思路很简单把所有模块里需要的自定义仓库搬到settings.gradle的dependencyResolutionManagement.repositories中。Groovy 写法dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { google() mavenCentral() maven { url https://jitpack.io } maven { url https://maven.aliyun.com/repository/public } } }Kotlin DSL.kts写法dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { google() mavenCentral() maven { url uri(https://jitpack.io) } maven { url uri(https://maven.aliyun.com/repository/public) } } }改完后把各个build.gradle里的repositories块删掉。注意不是只删 app 模块是所有模块。你可以在 Android Studio 的 Project 面板里全局搜索repositories {一个个确认。处理之后Gradle 不会再从模块级别解析仓库一切以 settings 为准团队协作也省心很多。这里补充一个容易踩的细节在旧版 SDK 文档里有时候让你在根目录build.gradle的allprojects块里加仓库allprojects { repositories { maven { url https://xxx.com/nexus/content/groups/public/ } } }如果你已经启用了FAIL_ON_PROJECT_REPOS这个allprojects同样会触发报错因为根build.gradle也算 project 级别的仓库声明。正确处理是把它迁移到settings.gradle或者把整个allprojects块删掉。3.2 方案二移除 build.gradle 中的仓库声明这个方案其实是方案一的简化版。如果你的项目只需要默认的google()和mavenCentral()settings.gradle里已经有了那么你只需要把所有模块build.gradle里多余的repositories块删干净即可。具体操作全局搜索所有repositories关键字。对每个出现的build.gradle文件确认它是否在dependencies块之前单独声明了仓库。如果这个仓库在settings.gradle中已经存在直接删除。如果存在 settings 中没有的仓库先把它补进settings.gradle再删除模块里的声明。删除之后重新 Sync。这个方案最干净不会改变仓库解析顺序也不会产生任何副作用。缺点是如果你有几十个模块手动清理工作量大建议用全局搜索逐个过不要靠肉眼翻目录树。3.3 方案三修改 repositoriesMode应急但不推荐如果你急着出包不想大动干戈也可以把settings.gradle里的FAIL_ON_PROJECT_REPOS改成PREFER_SETTINGSrepositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)这样项目模块里的repositories声明会被忽略但不会抛异常构建可以继续。为什么说不推荐因为PREFER_SETTINGS模式下模块里的仓库声明如果和 settings 不一致Gradle 会以 settings 为准模块里写错了也不会报错等于埋了一个“看起来生效但实际没生效”的暗雷。它适合短期过渡不适合长期保留。还有个更直接的PREFER_PROJECTrepositoriesMode.set(RepositoriesMode.PREFER_PROJECT)这会完全关闭集中管理所有模块继续用自己的仓库settings 里的仓库仅在模块找不到依赖时兜底。老项目迁移时偶尔用它来“先跑起来”但如果你把这种模式提交到团队仓库后面的人很难发现仓库配置的真实来源排查依赖问题时要多绕一圈。所以它只建议作为临时调试手段最终一定要落到方案一。3.4 方案四处理第三方插件内嵌的仓库声明有些第三方插件比如某些推送、支付、地图 SDK它们的 Gradle 插件会在apply时自动向项目里添加仓库。这时候你没有在build.gradle里写repositories但插件内部调用addRepository也会触发同样的报错。遇到这种情况你没法直接去改插件的源码除非你把它拷到本地改。推荐的排查办法是查看报错信息里 repository 的名称它会告诉你仓库名比如repository maven was added by build file xxx.gradle。如果提示是插件桩代码添加的去插件的官方文档找“使用新 Gradle 仓库配置”的说明。一般这些 SDK 都会更新适配方案要求你把仓库预先加在settings.gradle的dependencyResolutionManagement.repositories里。插件检测到仓库已存在就不会重复添加。如果一时找不到上游适配还有个折中办法在settings.gradle的pluginManagement.repositories里加上该仓库同时把dependencyResolutionManagement的模式调成PREFER_SETTINGS。注意这并不能保证百分之百解决问题不同插件的实现方式不一样但值得一试。4. 高频场景补充镜像仓库、Flutter 工程、依赖缓存4.1 配置国内镜像时如何一步到位很多报错的根源其实是“下载太慢”于是大家纷纷往build.gradle里加阿里云镜像仓库结果又触发了InvalidUserCodeException。与其零散加仓库不如在settings.gradle里一次性配好镜像dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { maven { url https://maven.aliyun.com/repository/public } maven { url https://maven.aliyun.com/repository/google } maven { url https://maven.aliyun.com/repository/gradle-plugin } google() mavenCentral() } }这样既是集中管理又解决了下载速度问题。Gradle 解析依赖时会按从上到下的顺序查找仓库把镜像放在前面命中率更高。注意镜像源和官方源尽量别混着乱写否则容易出现同一个依赖不同版本、缓存互相污染的问题。另外如果你维护的是团队公共仓库建议把私有 Nexus 或内部镜像地址作为标准避免每个成员各自在本地配置一遍。需要拉取本地 Maven 仓库包的时候也在 settings 里统一加mavenLocal()不要单独写到某个模块里。这样既避免报错也避免有人漏配导致构建环境不一致。关于“Gradle 下载慢”还要提一句这和仓库源是两码事。如果你遇到的是 Gradle 发行版 zip 本身下载超时报错类似Could not install Gradle distribution from ... java.net.SocketTimeoutException那是distributionUrl指向的网络地址太慢需要单独处理不是这篇仓库配置能解决的。4.2 Flutter 工程里这个报错怎么处理Flutter 项目打开 android 目录后看到的其实是标准的 Gradle 工程。Flutter 官方生成的settings.gradle里同样有dependencyResolutionManagement。但 Flutter 插件的生态历史包袱重不少插件包自己的android/build.gradle里带了repositories于是你执行flutter run或flutter build apk时就会遇到InvalidUserCodeException。处理方式其实和普通 Android 工程一样把插件需要的仓库统一加进android/settings.gradle的dependencyResolutionManagement.repositories里然后把插件build.gradle里的仓库声明删掉。不过插件是第三方库直接改插件源码会导致后续升级冲突。更稳的做法找到报错信息指出的具体插件模块路径。确认插件build.gradle里声明了哪些仓库。把这些仓库补到项目settings.gradle中。如果插件源码是你自己的顺手把它build.gradle里的repositories删掉。如果是纯第三方插件通常把仓库补进settings.gradle后构建就能跳过插件自身的仓库声明。热词里还提到you are applying flutters main gradle plugin imperatively using the apply script这个报错它和仓库配置不是同一个问题但经常一起出现。这个报错是 Gradle 版本升级后Flutter 主 Gradle 插件还在用旧式apply方式引入导致的解决思路是升级 Flutter SDK 或者在android/build.gradle中使用 plugins DSL 写法。建议你先处理仓库配置再排查插件应用方式两个问题同时存在时构建会按阶段逐个暴露。4.3 依赖缓存损坏的连环问题另一种容易和本报错弄混的情况是你明明已经改好了仓库配置Sync 时还是报Gradles dependency cache may be corrupt。这个报错通常出现在网络异常、依赖下载被中断之后。Gradle 缓存目录里的 metadata 和实际文件对不上解析依赖时直接罢工。排查步骤先停掉所有 Gradle 进程gradlew --stop。删除出问题的模块缓存目录一般位于~/.gradle/caches/modules-2/files-2.1/下对应 group 的目录。如果嫌麻烦可以把整个~/.gradle/caches/目录改名备份让 Gradle 重新下载。注意这会清掉所有模块缓存下载量巨大慎用。重新执行构建观察日志。这个问题的本质是缓存不可信和仓库配置策略无关但很多人在处理InvalidUserCodeException时顺手把缓存删了结果发现报错还在。建议先确认报错是“仓库配置冲突”还是“依赖下载失败”再看缓存。我自己的排查顺序是先看报错第一行异常类型InvalidUserCodeException直接去查仓库配置看到SocketTimeoutException、Could not resolve之类再去查网络和镜像源。5. 常见问题速查表与我的排错习惯5.1 常见报错速查表现象原因解决方案构建报InvalidUserCodeException提示 repository added by build file模块build.gradle里有repositories而 settings 设置了FAIL_ON_PROJECT_REPOS把仓库迁到settings.gradle或删掉模块仓库声明同样的报错但报错来自第三方插件插件内部动态添加仓库在settings.gradle中预置该仓库或升级插件版本修改PREFER_SETTINGS后构建通过但部分依赖解析异常settings 仓库不完整模块仓库被忽略把所有模块用到的仓库补充到settings.gradle构建时依赖下载超时或缓存损坏网络问题或缓存 metadata 异常配置镜像源、清理对应缓存目录Flutter 工程构建时报错插件自带repositories或 Flutter 插件应用方式过旧统一在android/settings.gradle配仓库插件改用 plugins DSL老项目升级 Gradle 后开始报错旧项目仓库写在build.gradle里迁移到dependencyResolutionManagement并删除allprojects仓库块5.2 我的排错习惯与最后建议再分享一个小习惯我在处理 Gradle 仓库问题时会先开启--info或--warning-mode all重新构建一次。Gradle 在PREFER_SETTINGS模式下如果发现模块仓库被忽略会在日志里打出清晰的警告包括被忽略的仓库名和来源文件。根据警告列表我可以一次性把所有模块的仓库声明清理干净不用每个文件翻。这个习惯帮我省了不少时间尤其是遇到几十个模块的大工程时非常管用。最后聊一下为什么我坚持不推荐用PREFER_PROJECT长期规避问题。依赖仓库是构建系统的地基如果每个 module 各自为政一旦某个成员在本地改了镜像源、某个 CI 机器上缓存策略不同构建结果就可能出现差异。集中到settings.gradle以后仓库清单是唯一的无论是本机构建、持续集成还是同事拉代码结果都一致。这也是 Gradle 官方把PREFER_SETTINGS/FAIL_ON_PROJECT_REPOS作为新项目默认方向的根本原因。顺着这个思路去处理报错你就不会只停留在“不报错就行”而是真正把依赖管理理顺。
