复合构建（Composite Build）

复合构建允许将多个独立的 Gradle 项目组合在一起构建，常用于本地开发模式（用本地源码替换远程依赖）。

使用场景

• 同时开发多个相互依赖的项目
• 在不发布到仓库的情况下测试库的变更
• 将公共构建逻辑抽取为独立项目

基本配置

// settings.gradle.kts
rootProject.name = "my-app"

// 包含本地项目（替代 implementation("com.example:my-lib:1.0")）
includeBuild("../my-lib") {
    dependencySubstitution {
        // 将对 my-lib 的依赖替换为本地项目
        substitute(module("com.example:my-lib")).using(project(":"))
    }
}

目录结构

workspace/
├── my-app/                    ← 应用项目
│   ├── settings.gradle.kts   ← includeBuild("../my-lib")
│   └── build.gradle.kts
└── my-lib/                   ← 库项目（独立 Git 仓库）
    ├── settings.gradle.kts
    └── build.gradle.kts

应用项目配置

// my-app/settings.gradle.kts
rootProject.name = "my-app"

// 在开发时使用本地库，而非从仓库下载
includeBuild("../my-lib") {
    dependencySubstitution {
        substitute(module("com.example:my-lib")).using(project(":"))
    }
}

// my-app/build.gradle.kts
dependencies {
    // 在 includeBuild 之前，这里从仓库下载
    // includeBuild 后，自动使用本地版本
    implementation("com.example:my-lib:1.0.0")
}

将构建逻辑提取为复合构建

// 用独立项目替代 buildSrc（更好的 IDE 支持和可发布性）
// settings.gradle.kts
pluginManagement {
    includeBuild("build-logic")   // 独立的构建逻辑项目
}

rootProject.name = "my-app"
include("core", "web")

project/
├── build-logic/               ← 独立构建逻辑项目
│   ├── settings.gradle.kts
│   ├── build.gradle.kts
│   └── src/main/kotlin/
│       └── java-conventions.gradle.kts
├── core/
├── web/
└── settings.gradle.kts

运行复合构建任务

# 构建所有包含的构建
./gradlew build

# 只构建特定项目的任务
./gradlew :my-lib:build

# 在包含的构建中运行任务
./gradlew --project-dir ../my-lib build

下一步

• 插件概述 - 了解 Gradle 插件体系
• 插件开发基础 - 开发可发布的插件