--refresh-dependencies 必须与构建任务（如 build 或 compileDebugSources）联用才生效，单独执行无效；它仅强制重检并下载未命中或过期的依赖，不删除合法缓存文件，对版本不变但内容更新的私有包需手动清理对应缓存目录。
执行 --refresh-dependencies 时必须带构建任务
直接运行 ./gradlew --refresh-dependencies 不会触发依赖刷新，Gradle 会报错或静默退出。它必须绑定一个实际的构建任务（比如 build、assemble 或 compileDebugSources），才能激活缓存刷新逻辑。
- 正确写法：
./gradlew build --refresh-dependencies（Mac/Linux）或gradlew.bat build --refresh-dependencies（Windows） - 最小开销推荐：
./gradlew :app:compileDebugSources --refresh-dependencies，只刷新 debug 编译所需依赖，比全量build快得多 - 注意空格：
--refresh-dependencies前后必须有空格，写成build--refresh-dependencies是无效命令（常见拼写错误）
为什么 --refresh-dependencies 有时没效果
它只强制重新下载「未命中缓存」或「元数据过期」的依赖，不会删除本地已存在的合法文件。如果远程包内容被覆盖但版本号不变（如 SNAPSHOT 覆盖、私有仓库误发），Gradle 默认仍信任本地缓存的校验值（SHA256），导致新内容根本不会拉取。
- 典型表现：改了远程 JAR，本地同步后代码仍走旧逻辑，
--refresh-dependencies无反应 - 真正需要的是清空对应坐标的缓存条目，例如删掉
~/.gradle/caches/modules-2/files-2.1/com.example/lib-core/1.2.3/整个目录 - 更安全的做法：先执行
--refresh-dependencies，再手动删该坐标下的.module和.pom文件，迫使 Gradle 重请求元数据
Android Studio 里点 Sync 不等于刷新缓存
AS 的「Sync Project with Gradle Files」只重新解析构建脚本和依赖声明，不触发网络请求，也不会校验或更新已缓存的二进制文件（JAR/AAR）。它等价于 ./gradlew projects，不是 --refresh-dependencies。
- 如果你刚换镜像源或修复了仓库配置，仅 Sync 是不够的
- 必须配合命令行执行带
--refresh-dependencies的任务，或在 AS 中打开 Terminal 手动运行 - AS 设置里的 «Always do a fresh build when syncing» 选项仅影响编译阶段，不影响依赖下载环节
刷新缓存前先确认问题根因
盲目刷新可能掩盖真实问题。先看日志里报错的关键字：
-
Could not GET 'https://...或Connection timed out→ 网络或仓库配置问题，刷新缓存无用 -
Could not find com.example:lib:1.2.3→ 坐标拼错、仓库没配对、或该版本根本不存在 -
Cached version not found或Metadata file not found→ 缓存损坏，此时--refresh-dependencies才是正解
缓存只是中间层，真正的源头永远在坐标、仓库、网络这三者之间。删缓存就像重启路由器——快，但不一定治本。
