最直接原因是~/.gradle/caches目录未迁移且不可跨机复用：该目录本地独占，新机器为空；Gradle版本不同时缓存结构不兼容，元数据无法识别；项目级.gradle目录含环境敏感信息，换机后自动失效；--offline首次必失败因无本地依赖缓存。
Gradle 全局缓存路径不一致导致缓存失效
换机器后缓存不命中，最直接的原因是 ~/.gradle/caches 目录根本没带过去。这个目录默认在用户主目录下，Windows 是 %USERPROFILE%\.gradle\caches，macOS/Linux 是 ~/.gradle/caches，但它是**本地独占、不可迁移**的缓存区。新机器上这个目录为空或结构不兼容，Gradle 就只能重下所有依赖。
注意：不是所有缓存都“不命中”——~/.gradle/caches/modules-2/files-2.*/ 里存的是下载的 JAR/AAR 文件，这部分内容理论上可复制，但 Gradle 不会自动识别你手动拷过去的文件，因为它的元数据（比如校验和、解析时间戳、模块坐标映射）全存在 ~/.gradle/caches/modules-2/metadata-* 和 ~/.gradle/caches/modules-2/module-metadata- 等子目录里，这些文件格式随 Gradle 版本演进，跨版本复制大概率触发 Corrupted cache 报错。
Gradle 版本与缓存结构强绑定
不同 Gradle 版本对缓存目录的组织方式不同。比如 Gradle 7.5 和 8.4 的 modules-2 内部结构就存在字段增删、序列化协议升级。哪怕你把整个 ~/.gradle/caches 拷到新机器，只要 Gradle 版本不一致，首次构建时就会触发自动清理或跳过读取，表现为「缓存未被复用」甚至报 Could not read metadata。
- 检查当前项目使用的 Gradle 版本：
gradle-wrapper.properties中的distributionUrl - 确认新机器上运行的是否为同一版本：
./gradlew --version - 如果版本不同，不要强行复用旧缓存，否则可能引发解析失败或静默跳过
本地构建缓存（.gradle 目录）也不跨机器生效
项目根目录下的 .gradle 是本地构建缓存（含 task 输出、配置缓存快照等），它默认不参与远程共享，且包含绝对路径、主机名、JVM 参数等环境敏感信息。换机器后即使保留该目录，Gradle 启动时也会检测到环境变更并主动失效它——你可能会看到日志里出现 Build cache is disabled because the build environment has changed。
这类缓存只适合单机反复构建时提速，不能靠拷贝迁移。真正能跨机器复用的是「远程构建缓存」，需要额外配置服务器（如 Gradle Enterprise 或自建 HTTP 缓存服务），并开启 org.gradle.caching=true 和 buildCache { remote(HttpBuildCache) { ... } }。
为什么 --offline 在新机器上必然失败
很多人换机器后想用 ./gradlew --offline build 避免网络请求，结果直接报 Could not resolve all files for configuration。这是因为 --offline 模式只跳过远程仓库请求，但所有依赖仍需从本地缓存中精确匹配——而新机器的 ~/.gradle/caches 是空的，连最基本的 AGP、Kotlin 插件都没下过，自然找不到任何东西。
正确做法是：首次构建必须联网，让 Gradle 完成依赖下载 + 元数据写入 + 缓存索引建立。后续增量构建才可能命中缓存。别指望第一次就离线成功。
缓存不命中最容易被忽略的一点：你以为在“复用”，其实 Gradle 根本没尝试读——它连缓存目录是否存在、是否可读、是否版本兼容都没通过，就直接走下载流程了。排查时别只盯日志里有没有「cache hit」字样，先看 ~/.gradle/caches 是否有对应版本的 modules-2 子目录，再确认里面是否有你依赖的 groupId/artifactId/version 路径结构。
