2. 启用构建缓存基础配置：settings.gradle 与 gradle.properties

原理：构建缓存如何工作

Gradle 构建缓存在 task 输出层面 工作：当两次构建的 task 输入（源代码、依赖版本、环境变量等）完全相同时，Gradle 直接复用先前缓存的输出产物，跳过 task 执行。这种跨项目、跨分支甚至跨机器的复用能力，是提升构建速度的核心手段。

实现流程：两处配置一个验证

步骤	配置文件	关键操作
1	settings.gradle	调用 enableBuildCache = true 声明缓存可用
2	gradle.properties	设置 org.gradle.caching=true 启用缓存，可选项如目录路径、压缩、远程缓存
3	构建命令行	使用 --info 或 Build Scan 确认缓存命中
4	缓存存储	检查 .gradle/caches/build-cache-1 目录或远程存储

settings.gradle 配置

在项目根目录的 settings.gradle（或 settings.gradle.kts）中，添加如下代码：

// settings.gradle
buildCache {
    local {
        enabled = true
    }
    // 如果需要远程缓存，可在此配置 remote 块
}
// 等价于设置 enableBuildCache = true（旧版写法）
enableBuildCache = true

gradle.properties 参数详解

在 gradle.properties 中设置以下参数以配合构建缓存：

# 启用构建缓存（必须）
org.gradle.caching=true

# 可选：本地缓存目录（默认 $GRADLE_USER_HOME/caches/build-cache-1）
org.gradle.caching.local.directory=/shared/cache

# 可选：缓存压缩（减少磁盘占用，略增加解压开销）
org.gradle.caching.local.compress=true

# 可选：远程缓存（仅在使用 remote 块时生效）
org.gradle.caching.remote.url=https://cache.example.com

配置流程 SVG

调试：验证缓存是否启用

执行构建时添加 --info 日志级别，Gradle 会输出缓存使用情况：

./gradlew assemble --info | grep -i "cache"

# 输出示例
[INFO] [org.gradle.caching.internal.LocalBuildCacheService] Stored artifact b6a9c1... in local build cache.
[INFO] [org.gradle.caching.internal.LocalBuildCacheService] Found artifact b6a9c1... in local build cache. Task :compileJava FROM-CACHE

也可以使用 Build Scan（--scan）在 Web 界面查看每个 task 的缓存来源，以及未命中的原因。

常见错误与解决方法

错误现象	原因	解决方式
Task 始终执行，从未命中缓存	settings.gradle 中缺少 enableBuildCache 或 buildCache 块	添加 enableBuildCache = true 或 buildCache { local { enabled = true } }
Build Scan 显示“cache disabled”	gradle.properties 中 org.gradle.caching 未设为 true	设置 org.gradle.caching=true
远程缓存返回 401 未授权	远程缓存 URL 配置正确但缺少认证头	在 settings.gradle 的 remote 块中配置 HTTP Basic 认证或
缓存目录空间不足	本地缓存默认无大小限制	设置 org.gradle.caching.local.removeUnusedEntriesAfterDays=7 自动清理

性能与稳定性优化建议

• 启用压缩：在 gradle.properties 中设置 org.gradle.caching.local.compress=true，减少磁盘 I/O 和网络传输量，适合 I/O 瓶颈项目。
• 隔离缓存目录：为 CI 服务器指定独立缓存路径（如 org.gradle.caching.local.directory=/ci-cache），避免与本地开发环境互相污染。
• 避免缓存的 task：通过 outputs.cacheIf { false } 排除非确定性的 task（如代码生成器），防止缓存结果被污染。
• 定期清理：在 CI 脚本中加入 ./gradlew cleanBuildCache，或在 Gradle 属性中设置 removeUnusedEntriesAfterDays 控制缓存生命周期。