本指南解释了如何将模块依赖项替换为模块源代码的本地分支，假设模块本身是用 Gradle 构建的。

使用本地分支可让您：

  • 对依赖项应用和测试自定义补丁。

  • 使用库的未发布版本。

  • 避免依赖已发布的二进制版本。

先决条件

  • 模块必须使用 Gradle 构建。

  • 您必须有模块源代码的本地副本。

  • 本地模块应设置为 Gradle 构建。

Gradle 复合构建会自动将外部依赖项替换为本地分支。

步骤 1：创建复合构建

假设您的初始项目结构如下所示：

project
├── settings.gradle(.kts)               (1)
└── my-app
    ├── build.gradle(.kts)              (2)
    └── src                             (3)
1 现有设置文件
2 现有构建文件
3 使用外部依赖项的现有应用程序项目

在此示例中，我们的应用程序依赖于 com.squareup.okhttp:okhttp:2.7.5，我们想使用它的本地分支

my-app/build.gradle.kts
dependencies {
    implementation("com.squareup.okhttp:okhttp:2.7.5")
}
my-app/build.gradle
dependencies {
    implementation("com.squareup.okhttp:okhttp:2.7.5")
}

首先，为依赖项的本地分支创建一个新文件夹

project
├── settings.gradle(.kts)
├── my-app
│   ├── build.gradle(.kts)
│   └── src
└── my-fork     (1)
1 包含本地分支的复合构建的新目录

在您的根项目的 settings.gradle(.kts) 文件中，添加一个指向 my-fork 的 includeBuild 语句

settings.gradle.kts
rootProject.name = "how_to_use_a_local_fork"

include("my-app")
includeBuild("my-fork")  // Path to your local fork
settings.gradle
rootProject.name = "how_to_use_a_local_fork"

include("my-app")
includeBuild("my-fork")  // Path to your local fork

这指示 Gradle 自动将外部依赖项坐标替换为您的本地构建。

步骤 2：包含本地分支

复合构建允许我们以最少的配置更改使用 okhttp 的本地版本。

假设本地分支已经是 Gradle 构建，将其复制或移动到 my-fork 目录中。分支模块将有自己的设置和构建文件。

更新后的项目结构将如下所示：

project
├── settings.gradle(.kts)
├── my-app
│   ├── build.gradle(.kts)
│   └── src
└── my-fork                             (1)
    ├── settings.gradle(.kts)           (2)
    └── okhttp
        ├── build.gradle(.kts)          (3)
        └── src                         (4)
1 okhttp 分支的新包含构建
2 分支模块的设置文件
3 分支模块的构建文件
4 分支模块的源代码

com.squareup.okhttp:okhttp:2.7.5 的源代码位于 okhttp/src 文件夹中。

设置文件应如下所示：

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

include("okhttp") // The forked module as a subproject
my-fork/settings.gradle
rootProject.name = "my-fork"

include("okhttp") // The forked module as a subproject

构建文件必须具有与 my-app 要求的相同的 GAV 坐标

my-fork/okhttp/build.gradle.kts
plugins {
    id("java-library")
}

// Matches implementation("com.squareup.okhttp:okhttp:2.7.5") in my-app build file
group = "com.squareup.okhttp" // Matches original dependency
version = "2.7.5" // Matches original dependency version = "2.7.5"
my-fork/okhttp/build.gradle
plugins {
    id("java-library")
}

// Matches implementation("com.squareup.okhttp:okhttp:2.7.5") in my-app build file
group = "com.squareup.okhttp" // Matches original dependency
version = "2.7.5" // Matches original dependency version = "2.7.5"

步骤 3：正常声明依赖项

在您的项目的 build.gradle(.kts) 中，继续使用与最初相同的外部坐标声明依赖项

my-app/build.gradle.kts
repositories {
    mavenCentral() // Don't remove this!
}

dependencies {
    implementation("com.squareup.okhttp:okhttp:2.7.5") // This doesn't need to change!
}
my-app/build.gradle
repositories {
    mavenCentral() // Don't remove this!
}

dependencies {
    implementation("com.squareup.okhttp:okhttp:2.7.5") // This doesn't need to change!
}

您不需要在 build.gradle(.kts) 文件中进行显式替换声明；Gradle 会自动处理替换。

通过此设置，Gradle 将自动使用您的本地分支，而不是从远程仓库下载依赖项。

步骤 4：故障排除

如果 Gradle 仍在尝试外部解析您的依赖项，请验证：

  • 本地分支 (build.gradle.kts) 指定的坐标 (group, name, 和 version) 与您的外部依赖项完全相同。

  • 您的 settings.gradle.kts 使用 includeBuild 正确引用了您的本地分支。

总结

Gradle 复合构建提供了一种简单有效的方法，用本地分支替换外部模块依赖项。