1. 多模块项目的依赖困境现状
当Android项目规模扩展到十几个甚至几十个模块时，每个模块的build.gradle文件里都充斥着重复的依赖声明。上周我在重构一个电商App时，发现同一个glide库在不同模块中被声明了27次，而且版本号从4.9.0到4.12.0竟然有5个不同版本共存。这种混乱直接导致编译时出现资源冲突，运行时发生ClassNotFoundException。
典型的依赖地狱症状包括：
- 版本冲突：不同模块引入同一库的不同版本
- 传递依赖爆炸：A依赖B，B依赖C，最终引入大量无用库
- 重复声明：相同依赖在多个模块重复定义
- 更新困难：升级某个库版本需要修改几十个文件
注意：Gradle默认会采用依赖版本仲裁策略，但实际项目中这种自动处理往往带来更多问题。比如当模块A需要okhttp 3.x而模块B强制使用okhttp 4.x时，编译可能通过但运行时必然崩溃。
2. 依赖集中化管理方案
2.1 创建版本目录文件
在项目根目录新建gradle/libs.versions.toml文件（Gradle 7.0+支持）：
toml复制[versions]
kotlin = "1.9.0"
glide = "4.15.1"
[libraries]
glide-core = { module = "com.github.bumptech.glide:glide", version.ref = "glide" }
glide-compiler = { module = "com.github.bumptech.glide:compiler", version.ref = "glide" }
[bundles]
glide = ["glide-core", "glide-compiler"]
2.2 在模块中引用统一依赖
模块级build.gradle示例：
groovy复制dependencies {
implementation(libs.glide.core) // 引用单个库
implementation(libs.bundles.glide) // 引用整个bundle
kapt(libs.glide.compiler) // kapt注解处理
}
2.3 版本同步的进阶技巧
对于多仓库项目，可以在settings.gradle中配置版本映射：
groovy复制dependencyResolutionManagement {
versionCatalogs {
libs {
from(files("../gradle/libs.versions.toml"))
// 覆盖特定版本
version("glide", "4.15.1")
}
}
}
实测发现，采用集中化管理后：
- 依赖变更只需修改1个文件
- 版本冲突减少90%以上
- 构建速度提升约15%（因为减少了依赖解析时间）
3. 模块化依赖的架构设计
3.1 分层依赖原则
我的项目通常采用以下分层结构：
code复制:app (可独立运行)
|
├── :feature (各业务特性模块)
│ ├── :feature-home
│ └── :feature-cart
|
├── :library (通用业务库)
│ ├── :lib-network
│ └── :lib-image
|
└── :base (基础组件)
├── :base-android
└── :base-kotlin
依赖流向必须遵守：
- 上层可以依赖下层（app → feature → library → base）
- 严禁下层依赖上层（base绝对不能依赖feature）
- 同层模块避免相互依赖
3.2 API与Implementation分离
关键区别：
groovy复制// 声明为api时，依赖会传递暴露给上层模块
api(project(":lib-network"))
// implementation依赖不会向上传递
implementation(project(":lib-utils"))
典型应用场景：
- 基础库的公共接口使用api
- 具体实现类使用implementation
- 第三方库除非必要都用implementation
经验：在重构旧项目时，先用
./gradlew dependencies --configuration releaseRuntimeClasspath命令查看完整的依赖树，优先把误用的api改为implementation。
4. 高级依赖治理技巧
4.1 排除传递依赖
当引入的库带来不需要的次级依赖时：
groovy复制implementation("com.squareup.retrofit2:retrofit:2.9.0") {
exclude(group = "com.squareup.okhttp3", module = "okhttp")
exclude(module = "gson") // 使用kotlinx.serialization替代
}
4.2 强制版本统一
在根build.gradle中强制指定版本：
groovy复制configurations.all {
resolutionStrategy {
force("org.jetbrains.kotlin:kotlin-stdlib:1.9.0")
// 遇到冲突时优先用指定版本
preferProjectModules()
}
}
4.3 动态版本的风险控制
虽然Gradle支持+动态版本，但在大型项目中应该：
groovy复制// 错误做法 - 可能导致不可预期的更新
implementation("com.google.android.material:material:1.+")
// 正确做法 - 锁定主版本
implementation("com.google.android.material:material:1.8") {
strictly("[1.8, 1.9)") // 只接受1.8.x版本
}
4.4 依赖分析工具
推荐使用以下工具辅助治理：
./gradlew buildHealth：生成依赖健康报告./gradlew dependencyUpdates：检查可用更新- Android Studio的"Dependency Viewer"（右侧边栏）
5. 构建性能优化
5.1 启用构建缓存
在gradle.properties中添加：
properties复制org.gradle.caching=true
# 远程缓存配置（适合CI环境）
org.gradle.remote.build-cache=1
org.gradle.remote.build-cache.push=true
5.2 配置并行构建
gradle.properties配置：
properties复制org.gradle.parallel=true
# 根据CPU核心数设置
org.gradle.workers.max=4
5.3 按需配置模块
避免每次构建所有模块：
kotlin复制// settings.gradle.kts
include(":app")
if (System.getenv("CI") == null) { // 本地开发时才包含
include(":benchmark")
}
6. 国内开发环境适配
6.1 镜像源配置
在gradle.properties中设置：
properties复制systemProp.http.proxyHost=mirrors.tencentyun.com
systemProp.http.proxyPort=80
systemProp.https.proxyHost=mirrors.tencentyun.com
systemProp.https.proxyPort=80
或者为特定仓库配置：
kotlin复制// settings.gradle.kts
dependencyResolutionManagement {
repositories {
maven {
url = uri("https://mirrors.cloud.tencent.com/nexus/repository/maven-public/")
}
}
}
6.2 依赖下载加速
使用Gradle的依赖预加载：
bash复制# 提前下载所有依赖
./gradlew --refresh-dependencies assemble
对于特定大型依赖（如NDK），可以手动下载后放入：
code复制~/.gradle/caches/modules-2/files-2.1/
7. 常见问题解决方案
7.1 依赖冲突错误
典型报错：
code复制Conflict with dependency 'com.google.code.gson:gson'
解决方案分三步：
- 查看完整依赖树：
./gradlew :app:dependencies - 确认冲突路径
- 使用
exclude或force解决
7.2 找不到符号错误
当出现cannot find symbol时，通常是因为：
- 注解处理器未正确配置（如漏了kapt）
- api/implementation使用错误
- 多模块间源码依赖未导出
检查要点：
groovy复制// 对于注解处理器
kapt("com.github.bumptech.glide:compiler:4.15.1")
// 对于多模块访问
api(project(":lib-public")) // 暴露接口
implementation(project(":lib-internal")) // 隐藏实现
7.3 构建速度过慢
优化建议：
- 启用Gradle Daemon：
org.gradle.daemon=true - 增加JVM堆大小：
org.gradle.jvmargs=-Xmx4096m - 使用最新Gradle版本（目前9.6.1）
- 定期清理缓存：
./gradlew cleanBuildCache
8. 实战案例：电商App依赖治理
以我最近优化的电商项目为例：
优化前状态：
- 38个模块
- 217个直接依赖项
- 最长构建时间26分钟
实施步骤：
- 创建统一的libs.versions.toml
- 用
dependencyUpdates识别过时依赖 - 重构模块层级，规范依赖流向
- 将89%的api改为implementation
- 配置CI缓存和并行构建
优化后效果：
- 依赖项减少43%
- 构建时间降至9分钟
- 冲突错误归零
关键指标对比：
| 指标 | 优化前 | 优化后 |
|---|---|---|
| 构建时间 | 26min | 9min |
| 依赖冲突次数 | 17 | 0 |
| 重复依赖项 | 63 | 2 |
这个案例证明，系统的依赖治理能显著提升大型项目的可维护性。建议每个季度做一次依赖健康检查，就像定期体检一样重要。