4. Gradle 构建缓存（Build Cache）与依赖缓存的区别：构建缓存 vs 依赖缓存、本地缓存 vs 远程缓存、启用远程构建缓存配置模板

在 AGP 升级过程中，许多开发者混淆了 Gradle 的构建缓存（Build Cache）和依赖缓存（Dependency Cache）。两者虽然都利用“缓存”提升构建速度，但存储内容、触发条件和生命周期截然不同。本章从原理、对比、本地/远程拓扑、配置模板四个层面厘清差异，并给出可直接落地的远程构建缓存配置。

4.1 构建缓存 vs 依赖缓存 —— 核心区别

4.2 本地缓存 vs 远程缓存

无论构建缓存还是依赖缓存，都可以分为本地和远程两层。下表总结各层的用途和风险。

4.3 启用远程构建缓存 —— 配置模板

Gradle 远程构建缓存允许将 Task 输出推送到共享的 HTTP 服务器（如 Gradle Build Cache Node 或自定义缓存后端），供团队所有机器命中。以下配置放置在项目根目录的 gradle.properties 或 settings.gradle.kts/settings.gradle 中。

Kotlin DSL — settings.gradle.kts

// 在 settings.gradle.kts 中配置远程构建缓存
buildCache {
    local {
        isEnabled = true                     // 启用本地构建缓存
        directory = File(rootDir, ".gradle/build-cache")
        removeUnusedEntriesAfterDays = 7     // 7天未使用自动清理
    }
    remote {
        url = uri("https://cache.company.com:8080/cache/")
        isEnabled = true
        isPush = true                        // 允许本机将缓存推送到远程
        // 可选鉴权配置
        credentials {
            username = "build-cache-user"
            password = System.getenv("GRADLE_CACHE_PASSWORD") ?: ""
        }
    }
}

Groovy DSL — settings.gradle

// settings.gradle
buildCache {
    local {
        enabled = true
        directory = "${rootDir}/.gradle/build-cache"
        removeUnusedEntriesAfterDays = 7
    }
    remote(HttpBuildCache) {
        url = 'https://cache.company.com:8080/cache/'
        enabled = true
        push = true
        credentials {
            username = 'build-cache-user'
            password = System.getenv('GRADLE_CACHE_PASSWORD') ?: ''
        }
    }
}

4.4 整体缓存拓扑关系图

下图展示了构建缓存与依赖缓存在一次构建中的位置和交互流程，以及本地/远程各层如何协作。

4.5 调试与验证缓存策略

启用远程构建缓存后，通过以下方式验证是否生效：

• 构建日志：添加 --info 查看 Task cache store 来源。命中远程时会显示 Remote，本地命中显示 Local。
• 清理实验：./gradlew clean 后第二次构建，若 Task 输出全部 FROM-CACHE 则缓存工作正常。
• 远程监控：检查缓存服务器的 PUT/GET 请求日志，确认本机是否有推拉动作。