远程缓存必须显式配置buildCache块，仅设org.gradle.caching=true仅启用默认本地缓存；需在settings.gradle中声明remote(HttpBuildCache)并指定url、push等参数，否则远程缓存不生效。
远程缓存必须配 buildCache 块，不能只靠 org.gradle.caching=true
org.gradle.caching=true 只是启用构建缓存总开关，它默认只开本地缓存。远程缓存必须显式声明 buildCache 配置块，否则 Gradle 根本不会尝试连接远程服务。
推荐在 settings.gradle（或 settings.gradle.kts）中配置，因为该文件在构建早期就被读取，且对所有子项目统一生效：
buildCache {
local {
enabled = true
}
remote(HttpBuildCache) {
url = "https://your-cache-server/cache/"
push = true
}
}
-
push = true表示当前构建产生的输出会上传到远程缓存（CI 流水线建议开启；开发者本地可设为false避免污染共享缓存） -
url必须以/cache/结尾，少斜杠或错路径会导致 404 或静默失败 - 若用 HTTP（非 HTTPS），需额外加
allowInsecureProtocol = true，但生产环境严禁这么做
Gradle 8.9+ 要用 HttpBuildCache，别写错类名
Gradle 7.0 起废弃了旧的 buildCache { remote(HttpBuildCache) { ... } } 写法，但很多人仍误写成 RemoteBuildCache 或漏掉括号里的类型参数——这会导致配置被完全忽略，无任何报错，缓存就是不生效。
正确写法只有这一种（Kotlin DSL）：
remote(HttpBuildCache) {
url = "https://your-cache-server/cache/"
push = true
}
- Java DSL 同理：
remote(HttpBuildCache.class, spec -> { ... }) - 拼错
HttpBuildCache（比如少个H、大小写错、加了Remote前缀）→ Gradle 不报错，但远程缓存形同虚设 - Gradle 9.x 已彻底移除旧接口，用错类名会直接构建失败
远程缓存服务器地址必须可访问，且带认证时要配 credentials
常见错误不是配置写得不对，而是网络或权限卡住：本地能 curl -I https://your-cache-server/cache/ 返回 200，不代表 Gradle 就能通——JVM 网络栈可能受代理、SSL 证书、DNS 缓存干扰。
如果缓存服务启用了 Basic Auth，必须显式提供凭证：
remote(HttpBuildCache) {
url = "https://your-cache-server/cache/"
push = true
credentials {
username = "gradle"
password = "secret-token"
}
}
- 密码不要硬编码，推荐从环境变量读：
password = System.getenv("GRADLE_CACHE_PASSWORD") - Android Studio 默认走系统代理，若公司强制代理，而缓存服务在内网直连地址，需在
gradle.properties加：systemProp.http.proxyHost=和systemProp.https.proxyHost=清空或绕过 - Docker 部署的缓存节点（如
gradle/build-cache-node:9.11）默认监听:5071，URL 应为http://localhost:5071/cache/，不是8080或80
命中率低？先检查 org.gradle.caching.debug=true 日志
远程缓存“开了却没用”是最难排查的问题。打开调试日志后，每次构建会在控制台输出每项任务是否命中本地/远程缓存，以及跳过原因。
在 gradle.properties 加一行：
org.gradle.caching.debug=true
- 看到大量
Not caching task ':app:compileJava' because it has no outputs→ 自定义 task 没声明outputs，Gradle 不敢缓存 - 看到
Remote cache miss: no entry found但本地也 miss → 输入指纹变了，比如 build script 里用了new Date()或System.getenv() - 看到
Could not fetch remote build cache entry→ 网络不通、证书异常、URL 权限不足，此时 debug 日志会带具体 HTTP 状态码
真正容易被忽略的是：远程缓存依赖配置缓存和构建缓存同时启用。如果 org.gradle.configuration-cache=true 因脚本不兼容失败，整个构建流程会回退到无配置缓存模式，间接拖慢远程缓存初始化速度——所以务必先确保配置缓存稳定，再调远程缓存。
