经常看到有团队把 Gradle 从 6.x 拉到 7.x改完 wrapper、跑一次 sync屏幕上直接糊出来一行红字Build was configured to prefer settings repositories over project repositories but repository maven was added by build file app/build.gradle。第一反应都是去搜然后就撞上了repositoriesMode这个以前从来没见过的属性。照着文档抄一行repositoriesMode.set(RepositoriesMode.PREFER_PROJECT)红字没了人也就走了——过两周依赖解析开始抽风某个内部构件死活拉不到又回头怀疑是不是私服挂了。这篇就把repositoriesMode掰开讲清楚它在 Gradle 7.0 之后到底扮演什么角色、三个取值各自会把构建带向哪个方向、在多模块和插件满天飞的工程里该选哪个以及升级过程中那些看着像它的错其实根本不是它的问题。刚上手 Gradle 的同学可以照着把仓库收口做一遍已经在维护大型多模块工程的老手建议重点看第三、六节那里是真正会踩坑的地方。1. 升级到 7.x 之后为什么大家突然开始查 repositoriesMode1.1 一条报错把问题顶到脸上先看报错本身。Gradle 给出的提示信息其实信息量很足不同小版本措辞略有差别但骨架一致基本都是三段式Build was configured to prefer settings repositories over project repositories but repository maven was added by build file app/build.gradle翻译成人话就是当前构建被配置成settings 里的仓库优先但你在app/build.gradle里又加了一个叫maven的仓库两件事冲突了。三段分别对应当前生效的模式、惹事的仓库名、谁加的。第三段最好用也最容易被忽略。它可能出现三种值by build file xxx.gradle——你自己写的by plugin com.xxx.yyy——某个插件在代码里加的by settings file settings.gradle——settings 自己加的这种情况一般是配置写重了。看到by plugin的时候你去项目里全文搜索repositories是搜不到的因为那行代码在插件的 jar 包里。这是排查这类问题的头号障碍后面第六节会专门说怎么定位。还有一种是Build was configured to fail if project repositories are declared but ...这是FAIL_ON_PROJECT_REPOS模式下的措辞语气更硬意思是不管你加什么只要项目级出现仓库声明就直接让构建失败。1.2 Gradle 7.0 前后到底动了什么得先把时间线捋清楚不然容易把锅扣错。集中式仓库声明这块能力不是 7.0 才有的它是 6.8 引入的孵化特性dependencyResolutionManagement块连同repositoriesMode一起进来7.0 正式转正、去掉孵化标记。所以升级到 7.0 之后才出现这个属性这个说法不太准确准确的说法是7.0 之后这套东西成了官方推荐的写法大量脚手架和工程模板开始默认往里写于是普通人第一次撞上它。与此同时 7.0 还顺手清理了一批陈年旧账比如compile、runtime这些老配置被彻底移除仓库url的赋值一律要走uri()包装url https://xxx这种直接扔字符串的写法在升级时经常报类型转换错误。这些改动和repositoriesMode一点关系都没有但它们会在同一次升级里集中爆发混在同一屏报错里很容易让人误以为是仓库模式在作妖。我见过的典型误判就是明明报的是url类型错误人却跑去改repositoriesMode越改越乱。还有一个关键事实值得记牢repositoriesMode的默认值是PREFER_PROJECT7.0 没有改这个默认值。也就是说一个干净的老工程原样升到 7.x不会因为仓库模式而失败。真正失败的那些多半是工程模板、公司脚手架或者新建工程向导里已经提前写好了PREFER_SETTINGS或FAIL_ON_PROJECT_REPOS老代码一进来就冲突。搞清楚这一点排查方向立刻从Gradle 坑我变成谁在我的 settings 里动了手脚。1.3 一句话说清它到底管什么repositoriesMode解决的是一个非常具体的问题当 settings 文件和项目构建脚本两处都声明了依赖仓库时听谁的。它不是一个合并开关而是优先级与准入开关。这里有个特别容易误解的点很多人以为两处声明会叠加成一个大列表实际不是。它是覆盖关系要么全听 settings 的要么全听项目的。用公司采购打个比方PREFER_PROJECT是各部门自己下单总部那份采购清单作废PREFER_SETTINGS是只认总部清单部门自己买的当没看见FAIL_ON_PROJECT_REPOS是部门敢自己下单流程直接驳回。理解了这三句话后面所有细节都是它们的推论。而之所以要把这个开关当回事是因为仓库列表一旦失控带来的不只是能不能拉到包的问题还有构建速度、依赖来源可信度、以及团队之间配置漂移这三笔隐形成本。2. 三种取值的行为差异、后果与选型2.1 PREFER_PROJECT默认值兼容优先行为很干脆只要某个项目里声明了任意一个仓库settings 里dependencyResolutionManagement.repositories声明的仓库就整份失效不是逐个比较、也不是取并集。反过来说如果这个项目一个仓库都没声明那就老老实实用 settings 的。这个任意一个就整份失效的语义是最反直觉的地方我第一次读文档时也反复确认了两遍。// settings.gradle dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.PREFER_PROJECT) repositories { mavenCentral() } }这套模式下mavenCentral()只在所有项目都没写仓库时才生效。只要有一个模块写了repositories { maven { ... } }那个模块就走自己的其他没写的模块继续用 settings 的——注意粒度是按项目计算的不是整个工程一刀切。选它的理由通常只有一个过渡期。工程里插件太多、模块太杂一时半会儿收不干净先用默认值让构建跑起来。代价是仓库治理彻底失效插件想加什么仓库就加什么仓库镜像配置、私服策略、离线构建全部形同虚设。2.2 PREFER_SETTINGS静默覆盖最容易被误用行为是 settings 的仓库优先生效项目里声明的包括插件偷偷加的被忽略掉。注意是忽略不是报错——构建照常跑只在部分版本的告警日志里能看到一句不疼不痒的提示。dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS) repositories { mavenCentral() } }这个模式最大的问题是静默失败。假设某个内部插件依赖一个只在公司私服上才有的构建期依赖它自己在代码里加了私服地址。你把模式切成PREFER_SETTINGS这个地址被忽略构建跑到一半报Could not find com.example:xxx:1.0.0。你打开build.gradle一看私服地址明明写在里面啊——但那是插件写的而且已经被忽略了你在项目里怎么找都找不到线索。我的建议是把它当止血带用不当长期方案先用它把构建从红色拉回绿色趁着能跑赶紧把缺的仓库补进 settings然后在 CI 上切到FAIL_ON_PROJECT_REPOS做最终校验。直接拿PREFER_SETTINGS当终态等于给自己埋一个只有换机器、换网络环境才复现的定时炸弹。2.3 FAIL_ON_PROJECT_REPOS强制收口团队协作首选行为最硬只要检测到任何项目级仓库声明——不管是你写的还是插件加的——配置阶段立刻失败构建根本进不到编译。dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { maven { url uri(https://repo.example.com/repository/maven-public/) } mavenCentral() } }它的价值在于把团队约定变成了构建期强制检查。口头约定仓库统一写在 settings 里这种事撑不过三个月尤其是有新人加入、有新模块从别的工程拷进来的时候。而FAIL_ON_PROJECT_REPOS会在第一次 CI 跑起来的时候就告诉你有人违规了哪一行哪个文件。代价也很实在改造初期会非常痛。历史工程里少说有十几个地方散落着仓库声明插件注入的那些更是防不胜防。我的做法是分两步走——先在本地或一个独立分支上开这个模式把报错一条条消灭等本地全绿了再合入主干避免影响其他人的日常开发节奏。2.4 三种模式对照与选型建议模式项目声明了仓库settings 声明了仓库构建是否中断典型使用场景PREFER_PROJECT项目仓库生效settings 整份失效仅当项目未声明时生效否老工程过渡期、插件生态复杂且短期无法收敛PREFER_SETTINGS被静默忽略生效否紧急止血、临时统一镜像、排查依赖来源FAIL_ON_PROJECT_REPOS直接失败生效是新工程、多模块主干、CI 强制校验选型的判断标准其实就一条这个工程里还有没有人有正当理由在模块内声明仓库。如果答案是没有直接上FAIL_ON_PROJECT_REPOS别犹豫如果答案是有但我不知道是哪个插件那先用PREFER_SETTINGS撑住同时把定位插件这件事排进迭代。PREFER_PROJECT只应该出现在我刚升完级先让它跑起来明天再说这个时间窗口里超过一周就是技术债。3. 别把三块仓库搞混作用域全景3.1 dependencyResolutionManagement 只管项目依赖这一块的职责边界必须刻在脑子里它管的是项目里configurations比如implementation、api、testImplementation、releaseRuntimeClasspath解析依赖时用哪份仓库列表。也就是build.gradle里那个裸的repositories { }块被它接管了。// build.gradle项目级 dependencies { implementation com.example.core:core-utils:2.3.1 }上面这个依赖会走dependencyResolutionManagement.repositories里的仓库去解析repositoriesMode影响的就是它。范围就这么大不多不少。3.2 pluginManagement 管插件且必须写在最前面插件解析走的是另一套pluginManagement.repositories。它和repositoriesMode完全无关你就算把模式设成FAIL_ON_PROJECT_REPOS插件仓库该从哪来还是从哪来。而且pluginManagement块必须是 settings 文件的第一个块前面只能有注释写在别的地方 Gradle 会直接报错。// settings.gradle.kts pluginManagement { repositories { maven { url uri(https://repo.example.com/repository/gradle-plugins/) } gradlePluginPortal() mavenCentral() } } dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { maven { url uri(https://repo.example.com/repository/maven-public/) } mavenCentral() } } rootProject.name demo include(:app, :core)这段是完整可用的骨架Groovy DSL 版本把include(:app)换成include :app、url uri(...)保持不变即可。注意两个块的仓库列表通常是不同的插件仓库要放插件门户依赖仓库不需要。3.3 buildscript 里的 repositories 完全不受约束这是踩坑率最高的一条。buildscript { repositories { ... } }解析的是构建脚本自身的 classpath比如各种 Gradle 插件 jar它走的是buildscript.repositories跟dependencyResolutionManagement是两套独立的东西。// build.gradle buildscript { repositories { maven { url uri(https://repo.example.com/repository/gradle-plugins/) } } dependencies { classpath com.example.tools:build-tools:1.4.0 } }很多人开了FAIL_ON_PROJECT_REPOS发现build.gradle里这段居然还能正常跑于是怀疑模式没生效。其实它本来就管不到这里。真要收口 buildscript 的仓库只能靠代码评审和自定义检查脚本repositoriesMode帮不上忙。3.4 included build 与 buildSrc 各自为政includeBuild引入的复合构建、以及buildSrc目录本质上都是独立的构建各自有自己的 settings。父工程设了FAIL_ON_PROJECT_REPOS不会自动传递下去子构建该怎样还怎样。所以在大型工程里你可能会遇到主工程明明收口了buildSrc里还躺着三个仓库的情况。处理办法很简单把buildSrc/settings.gradle或.kts也按同样的方式配一遍。别嫌麻烦buildSrc的依赖解析出问题的时候报错信息比主工程更难读因为它连模块名都不会给你。3.5 作用域对照速查配置位置影响什么受 repositoriesMode 约束必须写在pluginManagement.repositories插件解析否settings 文件第一个块dependencyResolutionManagement.repositories项目依赖解析是它就是开关本体settings 文件中任意位置项目repositories { }项目依赖解析是build.gradlebuildscript.repositories构建脚本 classpath否build.gradlebuildSrc/settings.gradlebuildSrc 自身否独立构建buildSrc 目录下这张表建议直接存进团队文档。仓库解析类的问题九成都能靠它快速定位到到底是哪一层出了问题。4. 实操把散落各处的仓库收敛到 settings4.1 第一步摸底把所有声明扫出来别急着改配置先搞清楚现状。Linux 或 macOS 下用grep -rn --include*.gradle --include*.gradle.kts -E repositories\s*\{ .Windows 的 cmd 环境findstr /s /n /c:repositories *.gradle *.gradle.kts第一遍只找repositories {把文件路径和行号列出来。然后针对每个命中位置再单独确认里面有没有mavenLocal()、flatDir、ivy {、maven { url ... }这些特殊写法。flatDir尤其要注意它绕开了正常的坐标体系收敛到 settings 里会出问题得单独处理或直接干掉。另外顺手跑一下./gradlew buildEnvironment它会把构建脚本 classpath 的依赖树和解析来源打出来能帮你发现一些静态搜索漏掉的、由插件动态注入的构建期依赖。4.2 第二步改写 settingsGroovy 与 KTS 双版本Groovy DSL 版本// settings.gradle pluginManagement { repositories { maven { url uri(https://repo.example.com/repository/gradle-plugins/) } gradlePluginPortal() mavenCentral() } } dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { maven { name internal url uri(https://repo.example.com/repository/maven-public/) } mavenCentral() } } rootProject.name demo include :app, :coreKotlin DSL 版本// settings.gradle.kts pluginManagement { repositories { maven { url uri(https://repo.example.com/repository/gradle-plugins/) } gradlePluginPortal() mavenCentral() } } dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { maven { name internal url uri(https://repo.example.com/repository/maven-public/) } mavenCentral() } } rootProject.name demo include(:app, :core)两个细节值得说。一是repositoriesMode.set(...)这种写法在任何版本都稳Groovy 下直接repositoriesMode RepositoriesMode.FAIL_ON_PROJECT_REPOS也能跑但如果你在多个 Gradle 版本之间来回切用.set()更省心。二是给私服仓库加个name构建日志和--info输出里会显示这个名字比默认的maven、maven2好认一百倍排查时能省不少时间。4.3 第三步清理 build.gradle 里的残留根工程的build.gradle里通常长这样// 改造前 allprojects { repositories { maven { url uri(https://repo.example.com/repository/maven-public/) } mavenCentral() } }// 改造后整段删掉别留空壳 // allprojects 里只留真正需要的配置比如统一的编译参数 allprojects { tasks.withType(JavaCompile).configureEach { options.encoding UTF-8 } }注意别只是把repositories { }里面清空、留下一个空块。空块在FAIL_ON_PROJECT_REPOS下不报错因为没声明具体仓库但会给后来人错误暗示这里本来是有仓库的可能以后还要加回来。直接删干净配合 git blame 一眼能看到历史。各子模块的build.gradle同理。这一步用第一步扫出来的清单逐个处理改完再跑一次 grep 确认没有漏网的。4.4 第四步对付插件偷偷加仓库这一步最费时间但也有章法。流程是这样第一跑一次构建从报错里把插件 id 抄下来形如by plugin com.example.foo。第二用--stacktrace拿完整堆栈./gradlew help --stacktrace堆栈里能找到插件内部调用repositories.maven { }的具体位置虽然看不到源码但类名和方法名足够你确认是哪个插件了。第三按优先级做取舍。优先升级插件新版本大多遵守了集中式仓库的约定尤其是主流的构建插件这两年基本都改过了。次选是把它需要的仓库补进 settings注意补的时候带上content过滤见第五节别让一个插件的私服地址污染所有依赖的解析路径。最后才是临时降级到PREFER_SETTINGS而且要在代码里加注释写清楚原因和移除条件。有一种做法是在 settings 里用gradle.beforeProject { }钩子把项目仓库清空我不太推荐。它确实能让构建跑起来但等于把所有仓库来源都变成了黑盒以后谁也不知道某个依赖是从哪拉下来的出问题时排查成本翻倍。4.5 第五步验证收口结果改完之后别只看 sync 成不成功跑这几条# 强制刷新依赖确认所有构件都能从 settings 声明的仓库拿到 ./gradlew --refresh-dependencies :app:dependencies --configuration releaseRuntimeClasspath # 检查构建脚本 classpath 有没有意外来源 ./gradlew buildEnvironment # 打开全部告警看有没有被忽略的弃用提示 ./gradlew help --warning-mode all--refresh-dependencies这一步很关键。Gradle 有本地依赖缓存默认在用户目录的.gradle/caches/modules-2下如果只跑普通构建很可能全部命中缓存你以为收口成功了换台机器直接崩。强制刷新能把真实解析路径完整走一遍。5. 顺手把仓库治理做扎实内容过滤与版本目录5.1 content 过滤让每个仓库只回答自己该回答的问题仓库收口之后下一个问题是Gradle 会按顺序挨个仓库尝试没命中就返回 404 再试下一个。仓库越多、顺序越靠后无谓的网络往返就越多。content块能告诉 Gradle这个仓库只负责这几组坐标其他的别来问。dependencyResolutionManagement { repositories { maven { name internal url uri(https://repo.example.com/repository/internal/) content { includeGroup(com.example.internal) includeGroupByRegex(com\\.example\\.internal\\..*) } } maven { name public url uri(https://repo.example.com/repository/maven-public/) content { excludeGroup(com.example.internal) } } mavenCentral() } }includeGroupByRegex里的反斜杠要写双份这是 Kotlin 字符串转义的锅第一次写基本都会错一遍。excludeGroup的价值在于防止同名构件从公共仓库误拉——内部构件如果恰好和公共坐标撞名那就不只是慢的问题了可能直接拉到错误的版本。5.2 exclusiveContent锁死某个坐标只能从指定仓库拿content是建议,exclusiveContent是规定。被它圈定的 groupGradle 只会去指定的那个仓库找别处一律不看。dependencyResolutionManagement { repositories { exclusiveContent { forRepository { maven { name internal url uri(https://repo.example.com/repository/internal/) } } filter { includeGroup(com.example.internal) } } mavenCentral() } }这段配置的意义在于供应链层面的确定性。内部构件必须在内部仓库解析这条规则如果只写在文档里早晚会有人为了图快加个mavenLocal()绕过去。写成exclusiveContent绕不过去。5.3 mavenContent 与 releasesOnly别让快照版本污染发布流程还有一个很实用的小配置用来限制仓库只提供正式版或只提供快照版maven { name internal-releases url uri(https://repo.example.com/repository/releases/) mavenContent { releasesOnly() } } maven { name internal-snapshots url uri(https://repo.example.com/repository/snapshots/) mavenContent { snapshotsOnly() } }不这么分的时候Gradle 会在 release 仓库里也去查-SNAPSHOT版本白白多一次 404。多模块工程里快照依赖又多累积起来相当可观。这属于典型的配置五分钟长期受益。5.4 把版本也一起收口versionCatalogs仓库收口解决的是从哪拿版本目录解决的是拿哪个版本。Gradle 7.0 同期引入的版本目录正好可以和仓库治理配套使用。# gradle/libs.versions.toml [versions] core 2.3.1 [libraries] core-utils { module com.example.core:core-utils, version.ref core }// settings.gradle.kts dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { maven { url uri(https://repo.example.com/repository/maven-public/) } mavenCentral() } versionCatalogs { create(libs) { from(files(gradle/libs.versions.toml)) } } }放在dependencyResolutionManagement里的好处是仓库策略、版本策略、仓库准入模式三件事集中在同一个小文件里评审时一眼能看完。分散在十几个build.gradle里的时代该过去了。5.5 收口带来的收益给个量级估算不用太精确算个大概就有体感。假设一个 20 模块的工程去重后有 120 个外部依赖改造前每个模块各自声明 3 个仓库改造后 settings 里配 2 个仓库。阶段仓库声明位置首次解析请求量级说明改造前20 个模块 × 3 仓库约 360 次元数据请求按依赖数 × 仓库数粗略估算未命中也要走一次往返改造后settings 统一 2 仓库约 120 至 240 次命中率提升后多数依赖一次命中加 content 过滤同上约 120 至 150 次私服不再被问公共依赖少掉大量无效探测这组数字是量级估算实际值受缓存命中、网络 RTT、仓库响应速度影响很大别拿去当性能报告。但方向是明确的仓库数量减半请求量就接近减半CI 上每次构建省下的几十秒一年下来很客观。6. 常见问题与排查实录6.1 报错指向 build.gradle但那行根本不是 repositories这是最典型的一种。报错说was added by build file app/build.gradle你打开对应行号一看是一行apply plugin: com.example.foo压根没有仓库声明。原因很直接插件在apply的时候执行了自己的配置代码里面调用了project.repositories.maven { }。Gradle 把责任归到了触发点所在的构建文件上而不是实际执行加仓库动作的插件代码。定位方式就是前面说的--stacktrace堆栈会指向插件内部的类。另外--info级别日志也会打出仓库被添加的时机配合时间线能判断是哪个插件在配置阶段动的手。找到之后按 4.4 节的取舍流程处理。6.2 切到 FAIL_ON_PROJECT_REPOS 之后开始大量 Could not find这种改完模式就跑不动的情况八成是 settings 的仓库列表不全。改造前的仓库分散在十几个文件里你未必全抄过来了。先用dependencyInsight精确看某个依赖的解析路径./gradlew :app:dependencyInsight \ --dependency core-utils \ --configuration releaseRuntimeClasspath \ --info输出里会列出 Gradle 尝试过的仓库以及每个仓库的响应。如果某个仓库压根没出现在尝试列表里说明它没进 settings如果出现了但报 404说明坐标或路径不对可能是私服的 group 路径拼接规则和公共仓库不一样。还有一种隐蔽情况仓库确实在 settings 里但被content过滤挡住了。这时候日志里会显示仓库被跳过之类的信息--info下能看到。加了过滤之后一定要回头验证一遍所有依赖别只验证主模块。6.3 mavenLocal 带来的本地能跑、CI 挂mavenLocal()会把本机 Maven 本地仓库加进解析范围。它的特点是解析出来的构件完全不做校验而且优先级取决于声明位置。开发机上因为之前手动install过某个内部包构建顺畅CI 上没有这个本地仓库直接找不到。我的处理原则是mavenLocal()不写进 settings 的公共仓库列表只在确实需要本地联调时通过开发者自己的初始化脚本临时加用完就撤。写进 settings 里当常驻配置早晚会变成团队级的偶发故障源。这条经验是用两次深夜排查换来的不太好受。6.4 混合工程里改了又被覆盖有些跨端或移动端工程构建脚本是由工具链自动生成的。你手动删掉repositories { }下次同步一跑它又回来了FAIL_ON_PROJECT_REPOS继续报错形成死循环。应对方式分两层短期用PREFER_SETTINGS兜住让构建先能跑同时去找生成源头把工具链版本升上去。这类工具链在新版本里基本都改成了往 settings 写仓库升级路径通常是通的。实在升不上去就在 CI 上单独跑一个检查脚本比对生成文件是否被改动把问题显式暴露出来而不是让它静默存在。6.5 改了仓库配置但不生效检查缓存。Gradle 的元数据缓存放在用户目录的.gradle/caches/modules-2下面仓库地址变了但缓存没失效的话可能继续用旧结果。先用--refresh-dependencies跑一次多数情况能解决。还是不行的话再考虑清掉对应的缓存目录但别养成一有问题就删缓存的习惯——那会掩盖真正的问题。6.6 常见问题速查表现象大概率原因处理方向报错指向 build.gradle 但该行无仓库声明插件在 apply 时注入仓库--stacktrace定位插件升级或补仓库切模式后出现 Could not findsettings 仓库列表不全或被 content 挡了dependencyInsight --info看尝试路径buildscript 里的仓库依然生效repositoriesMode不管 buildscript靠代码评审和自定义检查收口buildSrc 里还有仓库声明独立构建配置不继承单独给 buildSrc 配 settings本地正常 CI 失败依赖了mavenLocal()的产物移除常驻的 mavenLocal 声明改了配置无变化元数据缓存未失效--refresh-dependencies再考虑清缓存手改的配置反复被还原工具链自动生成构建脚本升级工具链或在 CI 加检查7. 几点实践体会新起一个工程我从第一天就把repositoriesMode设成FAIL_ON_PROJECT_REPOS。这个阶段成本最低因为还没人往里扔东西边立规矩边开发比半年后再来治理轻松十倍不止。等工程铺开了、十几个模块、一堆插件再想收口就是一场硬仗。老工程改造我一般分两个迭代。第一个迭代切PREFER_SETTINGS同时把 CI 上的--warning-mode all打开让所有被忽略的仓库声明都暴露在日志里一条条抄进 settings。第二个迭代再切FAIL_ON_PROJECT_REPOS这时候基本只剩插件注入的那几个钉子户要处理。中间这两三周别省省了就是给自己挖坑。最后一个小技巧把仓库声明只允许出现在 settings这条规则写成 CI 的一个 grep 检查跑在构建之前。几十行脚本的事比任何文档和口头约定都管用。人都会忘脚本不会。
经常看到有团队把 Gradle 从 6.x 拉到 7.x改完 wrapper、跑一次 sync屏幕上直接糊出来一行红字Build was configured to prefer settings repositories over project repositories but repository maven was added by build file app/build.gradle。第一反应都是去搜然后就撞上了repositoriesMode这个以前从来没见过的属性。照着文档抄一行repositoriesMode.set(RepositoriesMode.PREFER_PROJECT)红字没了人也就走了——过两周依赖解析开始抽风某个内部构件死活拉不到又回头怀疑是不是私服挂了。这篇就把repositoriesMode掰开讲清楚它在 Gradle 7.0 之后到底扮演什么角色、三个取值各自会把构建带向哪个方向、在多模块和插件满天飞的工程里该选哪个以及升级过程中那些看着像它的错其实根本不是它的问题。刚上手 Gradle 的同学可以照着把仓库收口做一遍已经在维护大型多模块工程的老手建议重点看第三、六节那里是真正会踩坑的地方。1. 升级到 7.x 之后为什么大家突然开始查 repositoriesMode1.1 一条报错把问题顶到脸上先看报错本身。Gradle 给出的提示信息其实信息量很足不同小版本措辞略有差别但骨架一致基本都是三段式Build was configured to prefer settings repositories over project repositories but repository maven was added by build file app/build.gradle翻译成人话就是当前构建被配置成settings 里的仓库优先但你在app/build.gradle里又加了一个叫maven的仓库两件事冲突了。三段分别对应当前生效的模式、惹事的仓库名、谁加的。第三段最好用也最容易被忽略。它可能出现三种值by build file xxx.gradle——你自己写的by plugin com.xxx.yyy——某个插件在代码里加的by settings file settings.gradle——settings 自己加的这种情况一般是配置写重了。看到by plugin的时候你去项目里全文搜索repositories是搜不到的因为那行代码在插件的 jar 包里。这是排查这类问题的头号障碍后面第六节会专门说怎么定位。还有一种是Build was configured to fail if project repositories are declared but ...这是FAIL_ON_PROJECT_REPOS模式下的措辞语气更硬意思是不管你加什么只要项目级出现仓库声明就直接让构建失败。1.2 Gradle 7.0 前后到底动了什么得先把时间线捋清楚不然容易把锅扣错。集中式仓库声明这块能力不是 7.0 才有的它是 6.8 引入的孵化特性dependencyResolutionManagement块连同repositoriesMode一起进来7.0 正式转正、去掉孵化标记。所以升级到 7.0 之后才出现这个属性这个说法不太准确准确的说法是7.0 之后这套东西成了官方推荐的写法大量脚手架和工程模板开始默认往里写于是普通人第一次撞上它。与此同时 7.0 还顺手清理了一批陈年旧账比如compile、runtime这些老配置被彻底移除仓库url的赋值一律要走uri()包装url https://xxx这种直接扔字符串的写法在升级时经常报类型转换错误。这些改动和repositoriesMode一点关系都没有但它们会在同一次升级里集中爆发混在同一屏报错里很容易让人误以为是仓库模式在作妖。我见过的典型误判就是明明报的是url类型错误人却跑去改repositoriesMode越改越乱。还有一个关键事实值得记牢repositoriesMode的默认值是PREFER_PROJECT7.0 没有改这个默认值。也就是说一个干净的老工程原样升到 7.x不会因为仓库模式而失败。真正失败的那些多半是工程模板、公司脚手架或者新建工程向导里已经提前写好了PREFER_SETTINGS或FAIL_ON_PROJECT_REPOS老代码一进来就冲突。搞清楚这一点排查方向立刻从Gradle 坑我变成谁在我的 settings 里动了手脚。1.3 一句话说清它到底管什么repositoriesMode解决的是一个非常具体的问题当 settings 文件和项目构建脚本两处都声明了依赖仓库时听谁的。它不是一个合并开关而是优先级与准入开关。这里有个特别容易误解的点很多人以为两处声明会叠加成一个大列表实际不是。它是覆盖关系要么全听 settings 的要么全听项目的。用公司采购打个比方PREFER_PROJECT是各部门自己下单总部那份采购清单作废PREFER_SETTINGS是只认总部清单部门自己买的当没看见FAIL_ON_PROJECT_REPOS是部门敢自己下单流程直接驳回。理解了这三句话后面所有细节都是它们的推论。而之所以要把这个开关当回事是因为仓库列表一旦失控带来的不只是能不能拉到包的问题还有构建速度、依赖来源可信度、以及团队之间配置漂移这三笔隐形成本。2. 三种取值的行为差异、后果与选型2.1 PREFER_PROJECT默认值兼容优先行为很干脆只要某个项目里声明了任意一个仓库settings 里dependencyResolutionManagement.repositories声明的仓库就整份失效不是逐个比较、也不是取并集。反过来说如果这个项目一个仓库都没声明那就老老实实用 settings 的。这个任意一个就整份失效的语义是最反直觉的地方我第一次读文档时也反复确认了两遍。// settings.gradle dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.PREFER_PROJECT) repositories { mavenCentral() } }这套模式下mavenCentral()只在所有项目都没写仓库时才生效。只要有一个模块写了repositories { maven { ... } }那个模块就走自己的其他没写的模块继续用 settings 的——注意粒度是按项目计算的不是整个工程一刀切。选它的理由通常只有一个过渡期。工程里插件太多、模块太杂一时半会儿收不干净先用默认值让构建跑起来。代价是仓库治理彻底失效插件想加什么仓库就加什么仓库镜像配置、私服策略、离线构建全部形同虚设。2.2 PREFER_SETTINGS静默覆盖最容易被误用行为是 settings 的仓库优先生效项目里声明的包括插件偷偷加的被忽略掉。注意是忽略不是报错——构建照常跑只在部分版本的告警日志里能看到一句不疼不痒的提示。dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS) repositories { mavenCentral() } }这个模式最大的问题是静默失败。假设某个内部插件依赖一个只在公司私服上才有的构建期依赖它自己在代码里加了私服地址。你把模式切成PREFER_SETTINGS这个地址被忽略构建跑到一半报Could not find com.example:xxx:1.0.0。你打开build.gradle一看私服地址明明写在里面啊——但那是插件写的而且已经被忽略了你在项目里怎么找都找不到线索。我的建议是把它当止血带用不当长期方案先用它把构建从红色拉回绿色趁着能跑赶紧把缺的仓库补进 settings然后在 CI 上切到FAIL_ON_PROJECT_REPOS做最终校验。直接拿PREFER_SETTINGS当终态等于给自己埋一个只有换机器、换网络环境才复现的定时炸弹。2.3 FAIL_ON_PROJECT_REPOS强制收口团队协作首选行为最硬只要检测到任何项目级仓库声明——不管是你写的还是插件加的——配置阶段立刻失败构建根本进不到编译。dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { maven { url uri(https://repo.example.com/repository/maven-public/) } mavenCentral() } }它的价值在于把团队约定变成了构建期强制检查。口头约定仓库统一写在 settings 里这种事撑不过三个月尤其是有新人加入、有新模块从别的工程拷进来的时候。而FAIL_ON_PROJECT_REPOS会在第一次 CI 跑起来的时候就告诉你有人违规了哪一行哪个文件。代价也很实在改造初期会非常痛。历史工程里少说有十几个地方散落着仓库声明插件注入的那些更是防不胜防。我的做法是分两步走——先在本地或一个独立分支上开这个模式把报错一条条消灭等本地全绿了再合入主干避免影响其他人的日常开发节奏。2.4 三种模式对照与选型建议模式项目声明了仓库settings 声明了仓库构建是否中断典型使用场景PREFER_PROJECT项目仓库生效settings 整份失效仅当项目未声明时生效否老工程过渡期、插件生态复杂且短期无法收敛PREFER_SETTINGS被静默忽略生效否紧急止血、临时统一镜像、排查依赖来源FAIL_ON_PROJECT_REPOS直接失败生效是新工程、多模块主干、CI 强制校验选型的判断标准其实就一条这个工程里还有没有人有正当理由在模块内声明仓库。如果答案是没有直接上FAIL_ON_PROJECT_REPOS别犹豫如果答案是有但我不知道是哪个插件那先用PREFER_SETTINGS撑住同时把定位插件这件事排进迭代。PREFER_PROJECT只应该出现在我刚升完级先让它跑起来明天再说这个时间窗口里超过一周就是技术债。3. 别把三块仓库搞混作用域全景3.1 dependencyResolutionManagement 只管项目依赖这一块的职责边界必须刻在脑子里它管的是项目里configurations比如implementation、api、testImplementation、releaseRuntimeClasspath解析依赖时用哪份仓库列表。也就是build.gradle里那个裸的repositories { }块被它接管了。// build.gradle项目级 dependencies { implementation com.example.core:core-utils:2.3.1 }上面这个依赖会走dependencyResolutionManagement.repositories里的仓库去解析repositoriesMode影响的就是它。范围就这么大不多不少。3.2 pluginManagement 管插件且必须写在最前面插件解析走的是另一套pluginManagement.repositories。它和repositoriesMode完全无关你就算把模式设成FAIL_ON_PROJECT_REPOS插件仓库该从哪来还是从哪来。而且pluginManagement块必须是 settings 文件的第一个块前面只能有注释写在别的地方 Gradle 会直接报错。// settings.gradle.kts pluginManagement { repositories { maven { url uri(https://repo.example.com/repository/gradle-plugins/) } gradlePluginPortal() mavenCentral() } } dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { maven { url uri(https://repo.example.com/repository/maven-public/) } mavenCentral() } } rootProject.name demo include(:app, :core)这段是完整可用的骨架Groovy DSL 版本把include(:app)换成include :app、url uri(...)保持不变即可。注意两个块的仓库列表通常是不同的插件仓库要放插件门户依赖仓库不需要。3.3 buildscript 里的 repositories 完全不受约束这是踩坑率最高的一条。buildscript { repositories { ... } }解析的是构建脚本自身的 classpath比如各种 Gradle 插件 jar它走的是buildscript.repositories跟dependencyResolutionManagement是两套独立的东西。// build.gradle buildscript { repositories { maven { url uri(https://repo.example.com/repository/gradle-plugins/) } } dependencies { classpath com.example.tools:build-tools:1.4.0 } }很多人开了FAIL_ON_PROJECT_REPOS发现build.gradle里这段居然还能正常跑于是怀疑模式没生效。其实它本来就管不到这里。真要收口 buildscript 的仓库只能靠代码评审和自定义检查脚本repositoriesMode帮不上忙。3.4 included build 与 buildSrc 各自为政includeBuild引入的复合构建、以及buildSrc目录本质上都是独立的构建各自有自己的 settings。父工程设了FAIL_ON_PROJECT_REPOS不会自动传递下去子构建该怎样还怎样。所以在大型工程里你可能会遇到主工程明明收口了buildSrc里还躺着三个仓库的情况。处理办法很简单把buildSrc/settings.gradle或.kts也按同样的方式配一遍。别嫌麻烦buildSrc的依赖解析出问题的时候报错信息比主工程更难读因为它连模块名都不会给你。3.5 作用域对照速查配置位置影响什么受 repositoriesMode 约束必须写在pluginManagement.repositories插件解析否settings 文件第一个块dependencyResolutionManagement.repositories项目依赖解析是它就是开关本体settings 文件中任意位置项目repositories { }项目依赖解析是build.gradlebuildscript.repositories构建脚本 classpath否build.gradlebuildSrc/settings.gradlebuildSrc 自身否独立构建buildSrc 目录下这张表建议直接存进团队文档。仓库解析类的问题九成都能靠它快速定位到到底是哪一层出了问题。4. 实操把散落各处的仓库收敛到 settings4.1 第一步摸底把所有声明扫出来别急着改配置先搞清楚现状。Linux 或 macOS 下用grep -rn --include*.gradle --include*.gradle.kts -E repositories\s*\{ .Windows 的 cmd 环境findstr /s /n /c:repositories *.gradle *.gradle.kts第一遍只找repositories {把文件路径和行号列出来。然后针对每个命中位置再单独确认里面有没有mavenLocal()、flatDir、ivy {、maven { url ... }这些特殊写法。flatDir尤其要注意它绕开了正常的坐标体系收敛到 settings 里会出问题得单独处理或直接干掉。另外顺手跑一下./gradlew buildEnvironment它会把构建脚本 classpath 的依赖树和解析来源打出来能帮你发现一些静态搜索漏掉的、由插件动态注入的构建期依赖。4.2 第二步改写 settingsGroovy 与 KTS 双版本Groovy DSL 版本// settings.gradle pluginManagement { repositories { maven { url uri(https://repo.example.com/repository/gradle-plugins/) } gradlePluginPortal() mavenCentral() } } dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { maven { name internal url uri(https://repo.example.com/repository/maven-public/) } mavenCentral() } } rootProject.name demo include :app, :coreKotlin DSL 版本// settings.gradle.kts pluginManagement { repositories { maven { url uri(https://repo.example.com/repository/gradle-plugins/) } gradlePluginPortal() mavenCentral() } } dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { maven { name internal url uri(https://repo.example.com/repository/maven-public/) } mavenCentral() } } rootProject.name demo include(:app, :core)两个细节值得说。一是repositoriesMode.set(...)这种写法在任何版本都稳Groovy 下直接repositoriesMode RepositoriesMode.FAIL_ON_PROJECT_REPOS也能跑但如果你在多个 Gradle 版本之间来回切用.set()更省心。二是给私服仓库加个name构建日志和--info输出里会显示这个名字比默认的maven、maven2好认一百倍排查时能省不少时间。4.3 第三步清理 build.gradle 里的残留根工程的build.gradle里通常长这样// 改造前 allprojects { repositories { maven { url uri(https://repo.example.com/repository/maven-public/) } mavenCentral() } }// 改造后整段删掉别留空壳 // allprojects 里只留真正需要的配置比如统一的编译参数 allprojects { tasks.withType(JavaCompile).configureEach { options.encoding UTF-8 } }注意别只是把repositories { }里面清空、留下一个空块。空块在FAIL_ON_PROJECT_REPOS下不报错因为没声明具体仓库但会给后来人错误暗示这里本来是有仓库的可能以后还要加回来。直接删干净配合 git blame 一眼能看到历史。各子模块的build.gradle同理。这一步用第一步扫出来的清单逐个处理改完再跑一次 grep 确认没有漏网的。4.4 第四步对付插件偷偷加仓库这一步最费时间但也有章法。流程是这样第一跑一次构建从报错里把插件 id 抄下来形如by plugin com.example.foo。第二用--stacktrace拿完整堆栈./gradlew help --stacktrace堆栈里能找到插件内部调用repositories.maven { }的具体位置虽然看不到源码但类名和方法名足够你确认是哪个插件了。第三按优先级做取舍。优先升级插件新版本大多遵守了集中式仓库的约定尤其是主流的构建插件这两年基本都改过了。次选是把它需要的仓库补进 settings注意补的时候带上content过滤见第五节别让一个插件的私服地址污染所有依赖的解析路径。最后才是临时降级到PREFER_SETTINGS而且要在代码里加注释写清楚原因和移除条件。有一种做法是在 settings 里用gradle.beforeProject { }钩子把项目仓库清空我不太推荐。它确实能让构建跑起来但等于把所有仓库来源都变成了黑盒以后谁也不知道某个依赖是从哪拉下来的出问题时排查成本翻倍。4.5 第五步验证收口结果改完之后别只看 sync 成不成功跑这几条# 强制刷新依赖确认所有构件都能从 settings 声明的仓库拿到 ./gradlew --refresh-dependencies :app:dependencies --configuration releaseRuntimeClasspath # 检查构建脚本 classpath 有没有意外来源 ./gradlew buildEnvironment # 打开全部告警看有没有被忽略的弃用提示 ./gradlew help --warning-mode all--refresh-dependencies这一步很关键。Gradle 有本地依赖缓存默认在用户目录的.gradle/caches/modules-2下如果只跑普通构建很可能全部命中缓存你以为收口成功了换台机器直接崩。强制刷新能把真实解析路径完整走一遍。5. 顺手把仓库治理做扎实内容过滤与版本目录5.1 content 过滤让每个仓库只回答自己该回答的问题仓库收口之后下一个问题是Gradle 会按顺序挨个仓库尝试没命中就返回 404 再试下一个。仓库越多、顺序越靠后无谓的网络往返就越多。content块能告诉 Gradle这个仓库只负责这几组坐标其他的别来问。dependencyResolutionManagement { repositories { maven { name internal url uri(https://repo.example.com/repository/internal/) content { includeGroup(com.example.internal) includeGroupByRegex(com\\.example\\.internal\\..*) } } maven { name public url uri(https://repo.example.com/repository/maven-public/) content { excludeGroup(com.example.internal) } } mavenCentral() } }includeGroupByRegex里的反斜杠要写双份这是 Kotlin 字符串转义的锅第一次写基本都会错一遍。excludeGroup的价值在于防止同名构件从公共仓库误拉——内部构件如果恰好和公共坐标撞名那就不只是慢的问题了可能直接拉到错误的版本。5.2 exclusiveContent锁死某个坐标只能从指定仓库拿content是建议,exclusiveContent是规定。被它圈定的 groupGradle 只会去指定的那个仓库找别处一律不看。dependencyResolutionManagement { repositories { exclusiveContent { forRepository { maven { name internal url uri(https://repo.example.com/repository/internal/) } } filter { includeGroup(com.example.internal) } } mavenCentral() } }这段配置的意义在于供应链层面的确定性。内部构件必须在内部仓库解析这条规则如果只写在文档里早晚会有人为了图快加个mavenLocal()绕过去。写成exclusiveContent绕不过去。5.3 mavenContent 与 releasesOnly别让快照版本污染发布流程还有一个很实用的小配置用来限制仓库只提供正式版或只提供快照版maven { name internal-releases url uri(https://repo.example.com/repository/releases/) mavenContent { releasesOnly() } } maven { name internal-snapshots url uri(https://repo.example.com/repository/snapshots/) mavenContent { snapshotsOnly() } }不这么分的时候Gradle 会在 release 仓库里也去查-SNAPSHOT版本白白多一次 404。多模块工程里快照依赖又多累积起来相当可观。这属于典型的配置五分钟长期受益。5.4 把版本也一起收口versionCatalogs仓库收口解决的是从哪拿版本目录解决的是拿哪个版本。Gradle 7.0 同期引入的版本目录正好可以和仓库治理配套使用。# gradle/libs.versions.toml [versions] core 2.3.1 [libraries] core-utils { module com.example.core:core-utils, version.ref core }// settings.gradle.kts dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { maven { url uri(https://repo.example.com/repository/maven-public/) } mavenCentral() } versionCatalogs { create(libs) { from(files(gradle/libs.versions.toml)) } } }放在dependencyResolutionManagement里的好处是仓库策略、版本策略、仓库准入模式三件事集中在同一个小文件里评审时一眼能看完。分散在十几个build.gradle里的时代该过去了。5.5 收口带来的收益给个量级估算不用太精确算个大概就有体感。假设一个 20 模块的工程去重后有 120 个外部依赖改造前每个模块各自声明 3 个仓库改造后 settings 里配 2 个仓库。阶段仓库声明位置首次解析请求量级说明改造前20 个模块 × 3 仓库约 360 次元数据请求按依赖数 × 仓库数粗略估算未命中也要走一次往返改造后settings 统一 2 仓库约 120 至 240 次命中率提升后多数依赖一次命中加 content 过滤同上约 120 至 150 次私服不再被问公共依赖少掉大量无效探测这组数字是量级估算实际值受缓存命中、网络 RTT、仓库响应速度影响很大别拿去当性能报告。但方向是明确的仓库数量减半请求量就接近减半CI 上每次构建省下的几十秒一年下来很客观。6. 常见问题与排查实录6.1 报错指向 build.gradle但那行根本不是 repositories这是最典型的一种。报错说was added by build file app/build.gradle你打开对应行号一看是一行apply plugin: com.example.foo压根没有仓库声明。原因很直接插件在apply的时候执行了自己的配置代码里面调用了project.repositories.maven { }。Gradle 把责任归到了触发点所在的构建文件上而不是实际执行加仓库动作的插件代码。定位方式就是前面说的--stacktrace堆栈会指向插件内部的类。另外--info级别日志也会打出仓库被添加的时机配合时间线能判断是哪个插件在配置阶段动的手。找到之后按 4.4 节的取舍流程处理。6.2 切到 FAIL_ON_PROJECT_REPOS 之后开始大量 Could not find这种改完模式就跑不动的情况八成是 settings 的仓库列表不全。改造前的仓库分散在十几个文件里你未必全抄过来了。先用dependencyInsight精确看某个依赖的解析路径./gradlew :app:dependencyInsight \ --dependency core-utils \ --configuration releaseRuntimeClasspath \ --info输出里会列出 Gradle 尝试过的仓库以及每个仓库的响应。如果某个仓库压根没出现在尝试列表里说明它没进 settings如果出现了但报 404说明坐标或路径不对可能是私服的 group 路径拼接规则和公共仓库不一样。还有一种隐蔽情况仓库确实在 settings 里但被content过滤挡住了。这时候日志里会显示仓库被跳过之类的信息--info下能看到。加了过滤之后一定要回头验证一遍所有依赖别只验证主模块。6.3 mavenLocal 带来的本地能跑、CI 挂mavenLocal()会把本机 Maven 本地仓库加进解析范围。它的特点是解析出来的构件完全不做校验而且优先级取决于声明位置。开发机上因为之前手动install过某个内部包构建顺畅CI 上没有这个本地仓库直接找不到。我的处理原则是mavenLocal()不写进 settings 的公共仓库列表只在确实需要本地联调时通过开发者自己的初始化脚本临时加用完就撤。写进 settings 里当常驻配置早晚会变成团队级的偶发故障源。这条经验是用两次深夜排查换来的不太好受。6.4 混合工程里改了又被覆盖有些跨端或移动端工程构建脚本是由工具链自动生成的。你手动删掉repositories { }下次同步一跑它又回来了FAIL_ON_PROJECT_REPOS继续报错形成死循环。应对方式分两层短期用PREFER_SETTINGS兜住让构建先能跑同时去找生成源头把工具链版本升上去。这类工具链在新版本里基本都改成了往 settings 写仓库升级路径通常是通的。实在升不上去就在 CI 上单独跑一个检查脚本比对生成文件是否被改动把问题显式暴露出来而不是让它静默存在。6.5 改了仓库配置但不生效检查缓存。Gradle 的元数据缓存放在用户目录的.gradle/caches/modules-2下面仓库地址变了但缓存没失效的话可能继续用旧结果。先用--refresh-dependencies跑一次多数情况能解决。还是不行的话再考虑清掉对应的缓存目录但别养成一有问题就删缓存的习惯——那会掩盖真正的问题。6.6 常见问题速查表现象大概率原因处理方向报错指向 build.gradle 但该行无仓库声明插件在 apply 时注入仓库--stacktrace定位插件升级或补仓库切模式后出现 Could not findsettings 仓库列表不全或被 content 挡了dependencyInsight --info看尝试路径buildscript 里的仓库依然生效repositoriesMode不管 buildscript靠代码评审和自定义检查收口buildSrc 里还有仓库声明独立构建配置不继承单独给 buildSrc 配 settings本地正常 CI 失败依赖了mavenLocal()的产物移除常驻的 mavenLocal 声明改了配置无变化元数据缓存未失效--refresh-dependencies再考虑清缓存手改的配置反复被还原工具链自动生成构建脚本升级工具链或在 CI 加检查7. 几点实践体会新起一个工程我从第一天就把repositoriesMode设成FAIL_ON_PROJECT_REPOS。这个阶段成本最低因为还没人往里扔东西边立规矩边开发比半年后再来治理轻松十倍不止。等工程铺开了、十几个模块、一堆插件再想收口就是一场硬仗。老工程改造我一般分两个迭代。第一个迭代切PREFER_SETTINGS同时把 CI 上的--warning-mode all打开让所有被忽略的仓库声明都暴露在日志里一条条抄进 settings。第二个迭代再切FAIL_ON_PROJECT_REPOS这时候基本只剩插件注入的那几个钉子户要处理。中间这两三周别省省了就是给自己挖坑。最后一个小技巧把仓库声明只允许出现在 settings这条规则写成 CI 的一个 grep 检查跑在构建之前。几十行脚本的事比任何文档和口头约定都管用。人都会忘脚本不会。
