Gradle多模块依赖仓库集中管理：repositoriesMode迁移指南

1. 先把 repositoriesMode 这个开关弄明白

很多人是在把构建脚本往 Gradle 7.0 上搬的时候，第一次见到repositoriesMode这个词的。它出现在settings.gradle的dependencyResolutionManagement块里，写法是repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)，看起来像一个不起眼的配置项，实际上它决定的是整个构建里「依赖到底从哪里下载」这个根本问题的裁决权归谁。具体说，它管的是这么一件事：当settings.gradle里声明了一套仓库、各个模块的build.gradle里又声明了一套仓库时，Gradle 该听谁的。三种取值分别对应「听模块的」「听 settings 的」「谁在模块里声明就直接报错」。这个问题在单模块小工程里几乎不存在，但在十个以上模块的中大型工程里，几乎必然出现过仓库声明不一致、同一依赖在不同模块解析到不同来源的情况。所以这篇内容适合三类人看：正在做 Gradle 6 到 7 升级、被构建报错卡住的；工程模块数量已经多到管不住仓库声明的；以及想提前把构建规范立起来、不想以后再返工的。下面我会把三个取值的行为差异、默认值为什么这么设计、迁移的分阶段策略、以及我在实际改造里踩过的坑，一次讲透。

1.1 一行报错背后的真实原因

先还原一个非常典型的现场。升级到 Gradle 7.x 之后，构建日志里冒出这样一行：

Build was configured to prefer settings repositories over project repositories but repository 'MavenRepo' was added by build file 'app/build.gradle'

这句话的翻译是：构建已经被配置成「优先使用 settings 里声明的仓库」，但你的app/build.gradle里又加了一个仓库，这个仓库被忽略了。注意，这是一条警告，构建还能继续跑。如果配置的是另一个更严格的值，同样的代码会直接让构建失败。

出现这行日志，通常意味着两件事同时发生了：第一，settings.gradle里已经写了dependencyResolutionManagement并且repositoriesMode不是默认值；第二，某些模块的build.gradle里还留着老的repositories { ... }块没有清理。这两个东西共存，就是冲突的来源。

为什么升级之后才爆出来？因为dependencyResolutionManagement这套机制本身是在 6.x 后期引入、在 7.0 正式稳定并大面积推广的。更关键的是，配套的 Android 构建插件在新版本里生成的项目模板，默认就把repositoriesMode设成了FAIL_ON_PROJECT_REPOS，而老项目模板里每个模块的build.gradle和根目录的allprojects块里都塞着google()、mavenCentral()、jcenter()。新模板遇上老代码，冲突就出现了。

所以你在排查这类问题时，第一个动作应该是打开settings.gradle，看看dependencyResolutionManagement里的repositoriesMode被设成了什么。很多人的困惑就来自于「我根本没改这个配置」，但项目模板生成的时候已经帮你改好了。

1.2 三个取值，一张表说清楚

RepositoriesMode这个枚举一共就三个值，但每个值的语义差别很大，尤其是「忽略」和「报错」这两种处理方式的区别，直接决定了迁移的难度。

这三个值的排列顺序其实是一条清晰的迁移路径：从「什么都不管」到「管但提醒你」再到「管且不让你犯错」。把这条路径设计成三个档位而不是两个，是很务实的做法，因为大型工程的仓库清理几乎不可能一步到位。

PREFER_PROJECT这个默认值需要单独说一下。它的含义是：如果某个模块自己声明了仓库，那就用模块的，settings 里那套被无视。这个设计的初衷是向后兼容——在没有这个机制的年代，仓库就是写在模块里的，直接改变解析行为会让大量老工程瞬间构建失败。但这也意味着，如果你在settings.gradle里兴冲冲地写了一套仓库，然后发现完全没生效，八成就是repositoriesMode还停在默认值上。这是新手最容易卡住的第一个点。

PREFER_SETTINGS的价值在于它给了你一个「观察期」。切换到这个值之后，构建结果会按照 settings 的声明走，但所有在模块里声明了仓库的地方都会打出警告，相当于 Gradle 帮你把需要清理的位置全列了出来。你可以先把警告收进 CI 日志，慢慢清理，不影响日常开发。

FAIL_ON_PROJECT_REPOS则是终态。它的意思是仓库声明只能有一处，任何模块级别的repositories { }都是错误。这看起来很霸道，但对于一个需要长期维护的工程来说，这个霸道是值得的——它保证了不可能有人偷偷在某次提交里往某个模块加一个私有的仓库地址，然后把整条依赖链搞乱。

1.3 为什么默认值不是最严格的那个

有人会问，既然集中管理明显更好，为什么默认值不直接设成FAIL_ON_PROJECT_REPOS？

因为 Gradle 的升级策略一贯是「不破坏现有构建」。一个构建脚本在 6.x 上跑得好好的，升到 7.0 之后如果因为仓库声明位置不对就直接挂掉，那升级成本会高到没人愿意动。所以官方选择了渐进路线：默认保持旧行为，把更严格的选择权交给使用者，同时在项目模板里默认启用严格模式，用新项目去推动整个生态往规范方向走。

从实践角度看，这个策略是有效的。这两年新起的工程基本都是FAIL_ON_PROJECT_REPOS起步，仓库声明集中在一处，新人接手时不用满工程找「这个依赖到底从哪下的」。而老工程的迁移节奏则由团队自己控制，急不来。

还有一点容易被忽略：repositoriesMode只影响模块的repositories { }，它管不到buildscript { }块里的仓库。buildscript里的 classpath 依赖有自己独立的一套仓库解析逻辑，不受dependencyResolutionManagement约束。所以你会看到一种情况：切到FAIL_ON_PROJECT_REPOS之后，模块里的repositories报错了，但buildscript里的maven { url ... }还好端端地跑着。这不是漏网，而是设计如此。这一点我在后面讲buildscript处理的时候会展开。

2. 仓库声明失控到底会带来什么麻烦

理解一个配置项的价值，最好的方式是想清楚「不配它会怎样」。仓库声明散落在各个模块里，短期内看不出问题，但随着模块数量增加、依赖规模变大，会逐渐演化出三种典型症状，而且这些症状往往不会立刻报错，而是以一种很隐蔽的方式影响构建结果。

2.1 三种常见的失控形态

第一种是声明漂移。根目录的allprojects块里声明了一套仓库，某个模块的build.gradle因为需要引入一个特殊依赖，又自己加了一行maven { url "..." }。过一段时间这个依赖不需要了，但这行仓库声明没人删。再后来另一个模块复制粘贴了这段配置。三个模块、三套略有差异的仓库列表，谁也不知道哪个是「正确」的。

第二种是顺序不一致。仓库解析是有顺序的，Gradle 会按声明顺序依次查找，谁先找到就用谁的。如果模块 A 写的是google()在前、mavenCentral()在后，模块 B 反过来写，那么当同一个依赖在两个仓库里都存在且内容不同时，两个模块可能拿到不同的构件。这种情况极少发生，但一旦发生，排查成本高得离谱，因为构建日志里通常不会告诉你「这个包是从哪个仓库来的」。

第三种是版本冲突被掩盖。散落的仓库声明往往伴随着散落的依赖版本，ext里的版本号各地各写一套，最后靠resolutionStrategy强行对齐。问题被压住了，但源头没解决。

这三种形态有一个共同点：它们在单次构建里可能都不会报错。问题积累到一定程度，才会以「本地能跑、CI 挂了」「清缓存之后就好了」这种诡异形式暴露出来。而repositoriesMode的作用，本质上是把这类问题从「运行时靠运气」提前到「配置期直接暴露」。

2.2 仓库的先后顺序真的会影响结果

值得单独强调一下仓库顺序这件事，因为它的影响比大多数人想象的要大。

假设你的仓库列表是这样：

repositories { maven { url = uri("https://内网私服地址/repository/maven-public/") } mavenCentral() }

同一个依赖坐标，如果内网私服里有缓存，就用私服的；没有就回落到公共仓库。这个顺序是对的——私服优先，公共仓库兜底。但如果顺序反了，每次都会先查公共仓库，查不到才走私服，构建速度会明显变慢，尤其在内网访问外网受限的环境里，这个延迟会被放大到不可接受。

更微妙的情况是同一个坐标在两边内容不一致。私服上可能缓存了一个损坏的、或者被覆盖过的构件，公共仓库上是干净的。谁在前面，谁就赢。这也是为什么集中管理时要配合仓库过滤（content { }），让每个仓库只负责它该负责的那部分坐标，从根上消除这种歧义。

2.3 集中之后能拿到的三个实际收益

讲完问题，说收益。把仓库声明收口到settings.gradle之后，能拿到的实际好处有三个，都是我在改造过程中实实在在感受到的。

第一是可审计。全工程的依赖来源只有一处声明，新人接手、安全审查、依赖升级评估，看一眼settings.gradle就够了，不用再遍历几十个模块的build.gradle去找有没有私货。

第二是可复现。仓库列表统一了，那么同一份代码在不同机器、不同时间拉下来，解析到的构件来源是一致的。配合依赖锁（dependencyLocking）使用，构建的可复现性会提升一个台阶。这一点在需要长期维护的分支上尤其重要——半年后重新打一个老版本的包，不用担心因为某个仓库下线导致依赖拉不到。

第三是构建更快。这一点容易被忽略。仓库列表越短、越精准，Gradle 在解析依赖时需要发起的元数据请求就越少。当你用content { }把每个仓库的职责切清楚之后，一个依赖归属哪个仓库是确定的，Gradle 不需要挨个试。在模块多、依赖多的大型工程里，这个优化能省下的时间是以分钟计的。

3. 动手改造：从散落声明到统一收口

理论说完，进入实操。我把整个改造拆成四步，顺序很重要，尤其是第二步到第三步之间的过渡，不要图快直接跳到最严格模式，否则会一次性冒出一堆报错，反而不知道从哪下手。

3.1 第一步：先把项目里的仓库声明摸清楚

这一步不用改任何代码，纯侦察。目标是回答两个问题：哪些文件里声明了仓库？每个仓库声明了哪些地址？

用文件搜索找repositories关键字是最直接的办法。搜索范围要覆盖所有build.gradle、build.gradle.kts、settings.gradle、settings.gradle.kts，以及buildSrc目录下的构建脚本——buildSrc是一个独立构建，它有自己的仓库声明，很容易被漏掉。

如果你用的是命令行，在工程根目录下跑一条 grep 就很方便：

grep -rn --include="*.gradle" --include="*.gradle.kts" \ -A 8 "repositories" . | grep -v "^--$"

或者用你顺手的编辑器全局搜索也一样。重点是把结果整理成一张清单，标明「文件名 + 仓库地址 + 这个仓库是为了什么加的」。第三列最关键，很多仓库是历史遗留，加的时候为了解决一个临时问题，问题早没了但配置留下了。这类仓库在迁移时可以直接删掉，不用搬过去。

侦察阶段还有一件事要做：确认当前settings.gradle里有没有已经存在的dependencyResolutionManagement块。如果有，说明之前已经有人动过这块，需要先搞清楚它现在的状态，别在别人没做完的改造上再叠一层。

提示：buildSrc、build-logic这类独立构建，以及includeBuild引入的复合构建，都不受主工程dependencyResolutionManagement的约束。它们各自维护自己的仓库，改造时要单独处理，别以为主工程改完就万事大吉。

3.2 第二步：在 settings 里搭好统一仓库

摸清家底之后，在settings.gradle里把统一仓库搭起来。这个阶段先不要急着设repositoriesMode，让它保持默认的PREFER_PROJECT，这样新加的仓库声明暂时不会影响现有构建，你有一个安全的试验期。

Groovy DSL 的写法：

// settings.gradle dependencyResolutionManagement { repositories { maven { name = "internal" url = uri("https://内网私服地址/repository/maven-public/") allowInsecureProtocol = false } google() mavenCentral() } }

Kotlin DSL 的写法：

// settings.gradle.kts dependencyResolutionManagement { repositories { maven { name = "internal" url = uri("https://内网私服地址/repository/maven-public/") } google() mavenCentral() } }

这里有几个细节值得说一下。

仓库的name属性建议显式指定。不指定的话 Gradle 会自动生成一个名字，在报错信息里会用它来指代这个仓库。显式命名之后，日志里出现repository 'internal'比出现MavenRepo要直观得多，排查时省事。

google()和mavenCentral()的顺序。如果你的工程依赖 Android 生态的构件，google()放前面会更快，因为 Android 相关的组件只在google()里有，先查它有更大概率命中。这一点在模块多的时候对构建速度影响不小。

老工程里的jcenter()要清掉。这个仓库这两年已经不太靠谱，很多构件拉不到或者不稳定。新版构建工具里它已经被标记为弃用，继续留着只会在解析失败时给你制造困惑。用mavenCentral()替代，个别只在jcenter上的老构件，看看能不能找到替代版本，实在找不到再单独用maven { url }指过去。

3.3 第三步：分阶段收紧 repositoriesMode

仓库搭好之后，开始收紧repositoriesMode。我建议分成两个阶段，每阶段观察一段时间。

第一阶段切到PREFER_SETTINGS：

dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS) repositories { /* ... */ } }

切完之后跑一次完整构建，把日志里的警告全部收集起来。这些警告会精确告诉你哪个文件的哪一行声明了仓库。拿着这份清单，逐个处理：能删的删掉，删了会影响构建的就搬到settings.gradle里去。

这个阶段可以持续一到两周，让 CI 上跑几轮，把平时不常触发的分支也覆盖到。有些模块可能只有特定构建变体才会用到某个仓库，日常开发碰不到，只在打包时才暴露。

第二阶段切到FAIL_ON_PROJECT_REPOS：

dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { /* ... */ } }

这一步切完，任何残留的模块级仓库声明都会变成硬错误。切之前确认上一阶段的警告已经清零，否则构建会直接挂。

注意：不要在同一个提交里同时做「清理模块仓库」和「切换严格模式」两件事。分开提交，出问题时才能快速定位是清理漏了还是模式切早了。回滚也方便。

3.4 buildscript 和插件仓库要单独收拾

前面说过，dependencyResolutionManagement管不到buildscript { }里的仓库。这部分要单独处理，处理位置是settings.gradle的pluginManagement块和各个build.gradle的buildscript块。

插件解析的部分，收口到settings.gradle：

pluginManagement { repositories { maven { name = "internal-plugins" url = uri("https://内网私服地址/repository/maven-public/") } gradlePluginPortal() google() mavenCentral() } }

pluginManagement的仓库列表是独立的一套，它只负责解析plugins { }块里声明的插件。注意gradlePluginPortal()通常要保留，很多社区插件只发布在那里。

buildscript { }块里的 classpath 依赖，如果还有残留的仓库声明，只能逐个模块清理，或者用根目录的allprojects { buildscript { repositories { ... } } }统一声明——但后者又会把仓库声明散回各个模块，跟集中管理的初衷相反。比较好的做法是把buildscript里真正需要的东西减到最少，能转成plugins { }声明的就转过去，转不了的再单独声明。

这一步做完，仓库声明的收口才算真正完成。很多团队的改造只做了dependencyResolutionManagement这一半，buildscript那半边一直留着，结果后来有人在某个模块的buildscript里加了一个私有仓库，同样的问题换个地方又出现了一遍。

4. 配合使用：让统一后的仓库更精准

仓库收口只是把声明集中了，但列表本身还是粗放的——每个仓库都可能被查询所有坐标。要真正发挥集中管理的价值，还得用上仓库过滤能力，把每个仓库的职责切清楚。

4.1 用 content 过滤缩小搜索范围

content { }块可以限定某个仓库只负责特定 group 或特定模块的构件。用google()举例，如果你的工程只依赖少量 Android 组件，可以这样写：

repositories { google { content { includeGroupByRegex("com\\.android.*") includeGroupByRegex("com\\.google\\.android.*") includeGroupByRegex("androidx\\..*") } } mavenCentral() }

这段配置的意思是：google()这个仓库只负责com.android、com.google.android、androidx开头的那些坐标，其他的都别问了，直接去mavenCentral()。

效果是立竿见影的。不加过滤的时候，Gradle 每解析一个依赖，都要先问google()有没有，没有才问mavenCentral()。加了过滤之后，非 Android 的坐标直接跳过google()，元数据请求次数明显下降。工程越大，这个差距越明显。

反过来也可以给私服加过滤，让它只负责内部坐标：

maven { name = "internal" url = uri("https://内网私服地址/repository/maven-public/") content { includeGroupByRegex("com\\.某前缀\\..*") } }

这样外部依赖就不会浪费一次请求去问私服了。注意过滤要写得准，includeGroupByRegex用错会导致本来能拉到的依赖突然拉不到，报错信息还不会告诉你「是被 content 过滤掉了」，只会说「找不到这个依赖」。所以每次加过滤之后，务必跑一次干净构建验证。

4.2 mavenLocal 该不该留

mavenLocal()指的是本地 Maven 仓库目录。很多老工程里都留着它，理由是「有时候要本地联调」。但它的副作用不小：本地仓库里的内容是不可控的，同一份构建脚本在不同机器上，可能因为本地仓库里恰好有某个包而成功，也可能因为你本地没有而失败。

FAIL_ON_PROJECT_REPOS模式下，mavenLocal()如果声明在模块里同样会报错，得搬到settings.gradle。我的建议是：默认不要放它，只在需要本地联调的临时分支上加，调完就删。如果团队确实频繁需要本地联调，那就明确约定——只在特定 profile 下启用，不进主构建。

还有一个相关问题：mavenLocal()里的构件没有校验机制，一个被覆盖过的本地包可能会让构建结果变得不可复现。在要求可复现构建的场景下，这个仓库应该彻底排除。

4.3 HTTP 仓库和 allowInsecureProtocol

新版本对 HTTP 协议的仓库地址做了限制，非 HTTPS 的地址需要显式声明allowInsecureProtocol = true才能用：

maven { name = "legacy-internal" url = uri("http://老私服地址/repository/maven-public/") allowInsecureProtocol = true }

这个开关是给内网环境留的口子。如果你们的内网私服还没上 HTTPS，升级之后不加这一行，构建会直接报错说协议不被允许。短期可以加这个开关绕过，长期还是建议把私服迁到 HTTPS——不光是为了应付这个检查，内网构件同样存在被篡改的风险。

allowInsecureProtocol只在确实需要的时候开，别图省事全局开。每多开一个，构建的可信边界就模糊一分。

5. 常见问题与排查实录

这一节我把改造过程中遇到的和收集到的问题整理成速查表，后面再补几个容易误判的边界情况。

5.1 报错与现象速查

排查这类问题的通用套路其实就三步：先看settings.gradle的repositoriesMode，再看报错里点名的那个文件，最后跑一次--refresh-dependencies排除缓存干扰。大部分问题卡在前两步就能定位。

5.2 几个容易误判的边界情况

有几个场景我在实际排查中反复遇到，都属于「看起来是这个问题其实不是」的类型，单独拎出来说。

一是allprojects和subprojects块里的仓库声明。这两个块写在根目录的build.gradle里，但作用范围是各个子模块。切到严格模式之后，这两个块里的repositories { }同样会触发错误，可报错指向的却是根构建脚本，容易让人以为是根工程的问题。实际上根工程本身没有声明仓库，是它给子模块「代发」的声明在报错。处理方式是把这两个块里的repositories整段删掉，仓库统一交给settings.gradle。

二是FAIL_ON_PROJECT_REPOS并不阻止repositories这个 DSL 的存在。它阻止的是「在项目级声明仓库」这个动作。如果你在settings.gradle的dependencyResolutionManagement.repositories里写，完全没问题；但如果某个插件在应用过程中往项目里注入了仓库声明，同样会触发错误。这种情况比较隐蔽，因为报错指向的是插件生成的代码位置，你得顺藤摸瓜找到是哪个插件干的。

三是复合构建（includeBuild）的仓库是独立的。主工程设了严格模式，不会影响被引入的复合构建。如果复合构建里也有仓库声明，需要单独处理。这一点在大型工程的拆分过程中经常被忽略，改完之后主工程干净了，但被 include 的那个构建还是老样子，出问题时很难联想到。

四是仓库切换后依赖缓存可能失效。从「模块级仓库」切到「settings 级仓库」，即使地址完全一样，Gradle 也可能认为这是不同的仓库来源，从而重新下载。这在 CI 上表现为「第一次跑特别慢」。不要慌，这是正常的，跑过一次之后就恢复了。提前跟团队打个招呼，避免有人在 CI 变慢的时候乱改配置。

5.3 踩过的坑和几条实在的建议

改造过程中有几个坑我印象比较深，写出来给后来人省点时间。

第一个坑是清理顺序。一开始我图快，直接把repositoriesMode设成了FAIL_ON_PROJECT_REPOS，然后一次性删除所有模块的repositories块。结果构建报了一堆「找不到依赖」的错误，因为有些模块依赖的构件确实只在某个模块单独声明的仓库里有，那个仓库地址我在删的时候没记下来。后来回滚重做，老老实实按PREFER_SETTINGS过渡，逐个搬仓库地址，才顺利推完。教训就是：删之前先把地址抄下来，别指望从版本历史里翻。

第二个坑是私服依赖content过滤写太窄。有个内部构件用的是com.某前缀.某模块这样的坐标，我在过滤规则里只写了com.某前缀.core，结果某模块拉不到。报错信息是「找不到依赖」，完全没提过滤的事，排查了半天才发现是includeGroupByRegex写窄了。所以过滤规则写完，一定要跑一次全量构建验证，别只看局部模块。

第三个坑是buildSrc被遗忘。主工程的仓库收口做得干干净净，构建也绿了。过了一个月，有人在buildSrc里加了个新的依赖，发现拉不到——因为buildSrc的仓库声明还是老一套，而那个私服地址已经调整过了。buildSrc是独立构建，它不会读主工程的settings.gradle。这条建议很朴素：改造清单里一定要把buildSrc、build-logic、includeBuild的目录都列上。

最后一个建议，关于「什么时候适合切严格模式」。我的判断标准是：当你的工程满足「模块数量超过五个」「依赖来源超过两个仓库」「有 CI 且构建频率高」这三条中的两条时，就值得切。少于这个规模，切了收益不大，反而增加了配置成本。但如果工程已经在往大走，那就趁早切，越晚改，散落的仓库声明越多，清理成本越高。

我个人在实际操作中的体会是，repositoriesMode这个开关本身的价值不在于那三行配置，而在于它逼着团队把「依赖从哪来」这件事说清楚。很多工程跑了几年，没人能完整讲出依赖来源的全貌，全靠构建能跑就行。切一次严格模式，相当于给工程做了一次依赖体检，顺带把历史遗留的、没人知道为什么存在的仓库地址清理掉。这个副产品，往往比集中管理本身更有价值。