Flutter配置Gradle缓存后添加依赖出现Gradle报错

1. 先校验基础配置是否真的生效 #

• 分别执行gradle -v、which gradle确认当前终端调用的Gradle是你手动配置过缓存、加入PATH的版本，重点排查是否被Flutter自带的内嵌Gradle覆盖：空Flutter项目默认使用Flutter SDK路径下flutter/bin/cache内嵌的Gradle版本，你给系统全局Gradle做的缓存配置不会自动作用于这个内嵌版本，空项目依赖少刚好初始化时已经下完所以能跑，加新依赖触发版本/依赖校验时就会暴露问题。
• 打开全局配置文件~/.gradle/gradle.properties，确认org.gradle.caching=true已开启，gradle.user.home配置的是你存放离线缓存的绝对路径，不要写相对路径避免识别失效。

2. 定位具体失败点 #

• 不要只看Flutter输出的笼统Gradle报错，进入项目的android目录，执行./gradlew assembleDebug --stacktrace --info打印完整构建日志，找到标记为Could not resolve、DOWNLOAD、FAILED的条目，明确具体是哪个依赖、哪个版本、请求的哪个仓库地址出的问题。
• 重点核对日志里的仓库请求地址：多数情况下配置不生效是因为新加的依赖、自带的构建插件配置的公网仓库优先级高于你配置的本地缓存/离线仓库，离线环境下连不上公网就会一直重试下载直到超时失败。

3. 针对性修复 #

• 对齐Gradle版本：打开android/gradle/wrapper/gradle-wrapper.properties查看distributionUrl指定的Gradle版本，要么把该版本替换为你本地已经做好离线缓存的版本，要么直接把distributionUrl改成本地离线包的file协议地址，比如distributionUrl=file\:/opt/gradle/gradle-7.5-all.zip，避免Gradle Wrapper自行联网下载发行包。
• 补全全量缓存：找一台有网络的设备拉取同一份项目代码，在项目根目录执行./gradlew build --refresh-dependencies拉取所有依赖，等构建完成后把~/.gradle/caches目录整体打包，覆盖到离线设备的对应缓存路径，注意不要遗漏caches/modules-2（依赖包缓存）和caches/transforms-3（AAR转换缓存）两个核心目录，后者缺失也会触发重新下载。
• 强制开启离线模式：在项目根目录的gradle.properties中添加org.gradle.offline=true，或者构建时追加--offline参数，此时Gradle会完全禁止网络请求，缺失依赖时会直接抛出明确的缺失项错误，不会无限重试下载。
• 调整仓库优先级：打开android/build.gradle，分别找到pluginManagement、dependencyResolutionManagement两个块下的repositories配置，把mavenLocal()放在仓库列表的最顶部，注释掉公网仓库地址，确保Gradle优先从本地缓存查找依赖。

4. 高频踩坑点排查 #

• 不要忽略传递依赖：新增的依赖往往会引入多层传递依赖，仅缓存你手动添加的那一个包远远不够，有网环境下可以执行./gradlew dependencies打印全量依赖树，确认所有层级的依赖都写入本地缓存后再往离线设备迁移。
• 补全构建插件缓存：Android Gradle插件、Kotlin插件等构建脚本类依赖同样存放在Gradle缓存目录，新加的依赖如果要求更高版本的构建插件，本地缓存不匹配也会触发下载，注意对齐android/build.gradle中com.android.tools.build:gradle的版本和本地缓存版本。
• 检查缓存目录权限：如果Gradle缓存目录是通过root用户拷贝的，当前构建用户没有目录读权限，Gradle会判定缓存缺失触发重下，执行chmod -R 755 ~/.gradle给当前用户分配缓存目录的读权限即可。

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