3. 配置根项目 build.gradle

多模块 Gradle 构建的根项目 build.gradle 是全局配置的起点。它将配置策略分为三个层级：根项目自身、所有项目（含根）、仅子项目。核心控制手段是 allprojects 和 subprojects 闭包，配合全局仓库与通用插件声明，实现“一处定义，到处生效”的复用目标。

1. 全局仓库与通用插件

全局仓库使用根项目顶层的 repositories 块声明；若同时使用 allprojects，则建议在 allprojects 内声明，确保所有子项目也会继承。

通用插件（如 java-library、maven-publish）通常通过 plugins 块置于根脚本顶部，或放入 allprojects 中的 apply plugin。现代 Gradle 推荐使用 plugins 块 + apply false 模式统一版本管理。

// 根项目 build.gradle
plugins {
    id 'java-library' apply false      // 声明但不立即应用
    id 'maven-publish' apply false
    id 'com.github.johnrengelman.shadow' version '7.1.2' apply false
}

allprojects {
    group = 'com.example'
    version = '1.0.0'

    repositories {
        mavenCentral()
        maven { url 'https://jitpack.io' }
    }
}

subprojects {
    apply plugin: 'java-library'

    java {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }

    dependencies {
        testImplementation 'org.junit.jupiter:junit-jupiter:5.9.2'
    }
}

2. allprojects 与 subprojects 语义对比

3. 配置流程图：根脚本执行逻辑

4. 实战步骤：构建稳健的根配置

1. 声明插件版本：在 plugins 块中用 apply false 统一管理，避免子项目间版本碎片。
2. 配置全局元数据：在 allprojects 中设置 group、version 以及仓库地址。
3. 定义子项目默认构建行为：在 subprojects 中应用通用插件（如 java-library）、统一 Java 版本、添加通用测试依赖。
4. 差异化配置下放到子项目：每个子项目的 build.gradle 只保留独有依赖、专属插件或特殊任务。
5. 验证配置继承：运行 gradle projects 和 gradle dependencies 检查各子项目是否正确继承了仓库和版本。

5. 常见错误与调试

• 根项目错误地参与了编译：根项目通过 allprojects 应用了 java-library，导致根目录下产生了 build 目录，且根项目的 src/main/java 也被编译。解决方案：改为 subprojects 应用插件。
• 仓库声明在子项目内重复：若未在 allprojects 声明仓库，每个子项目的 build.gradle 都要写一遍 repositories，且易引发不一致。统一放在 allprojects 中一次解决。
• 依赖版本冲突：不同子项目通过 implementation 引入同一库的不同版本。建议在 subprojects 的 dependencies 中使用 constraints 或借助 java-platform / version catalog 统一版本。
• 配置延迟与顺序问题：若在 allprojects 中读取子项目的属性（如 project.name），需注意配置阶段尚未完成。避免在 allprojects 闭包中执行依赖于子项目配置的任务。

// 错误示例：在 allprojects 中直接 apply plugin，导致根项目也被编译
allprojects {
    apply plugin: 'java-library'  // 不推荐
    repositories { mavenCentral() }
}

// 正确示例：只对子项目应用插件
subprojects {
    apply plugin: 'java-library'
}

6. 扩展：按生命周期精细化配置

除了 allprojects 和 subprojects，Gradle 还支持在 gradle.beforeSettings 和 gradle.settingsEvaluated 中注入早期配置。对于多模块项目，建议遵循以下粒度划分：

遵循此层级，可使大型多模块项目保持配置整洁、易于排错，并且最大程度复用代码。