Gradle缓存中同一版本依赖重复出现的原因及解决方法

成因分析 #

• jars-9是Gradle的传统JAR缓存目录，存储的是从仓库拉取的原始JAR文件，保留了仓库端的压缩格式，无额外处理。
• modules-2是Gradle引入模块元数据机制后新增的缓存目录，存储的是经过Gradle标准化处理的依赖文件：会对JAR重新执行压缩（默认用Deflater算法），同时生成模块描述文件，用于更高效的依赖解析和版本冲突处理。
• 当项目同时触发两种依赖解析逻辑时（比如混合使用基于POM的传统依赖和支持模块元数据的依赖），Gradle会分别在两个目录缓存同一份依赖的不同压缩版本，最终造成重复存储，导致缓存体积膨胀20%-30%。

规避方案 #

1. 统一依赖解析模式 #

在项目根目录的settings.gradle（或settings.gradle.kts）中配置，强制Gradle优先使用模块元数据解析，减少jars-9目录的缓存写入：

// Groovy DSL
dependencyResolutionManagement {
    repositories {
        mavenCentral {
            metadataSources {
                gradleMetadata() // 优先使用模块元数据
                mavenPom()       // 无元数据时回退到POM
            }
        }
    }
}

// Kotlin DSL
dependencyResolutionManagement {
    repositories {
        mavenCentral {
            metadataSources {
                gradleMetadata()
                mavenPom()
            }
        }
    }
}

配置后，大部分依赖会直接写入modules-2，仅少数无模块元数据的依赖会落到jars-9，大幅降低重复率。

2. 清理冗余缓存 #

在CI流水线上传缓存前，清理无效或冗余的缓存文件：

• 执行gradle cleanBuildCache命令，让Gradle自动清理过期、无效的缓存内容。
• 若确认项目已无需依赖jars-9目录，可直接删除该目录（rm -rf ~/.gradle/caches/jars-9），但需测试验证，避免触发重新拉取依赖导致CI耗时增加。

3. 优化CI缓存范围 #

不要直接打包整个.gradle目录，仅缓存必要的子目录：

• 优先缓存~/.gradle/caches/modules-2
• 缓存任务输出缓存目录（如~/.gradle/caches/build-cache-*）
• 跳过jars-9目录（已统一解析模式时）

4. 使用Gradle官方远程构建缓存 #

替换自行打包ZIP上传S3的方式，使用Gradle原生的远程构建缓存功能。Gradle会自动处理缓存的去重、增量更新和版本管理，从根源避免重复存储相同内容的文件。

内容的提问来源于stack exchange，提问作者roookeee