Gradle Wrapper仅在本地无对应版本缓存时才下载发行包；反复下载说明缓存缺失或损坏，根本原因多为路径错误、权限不足、网络代理或distributionUrl未正确指向国内镜像源（如清华源https://mirrors.tuna.tsinghua.edu.cn/gradle/）。
Gradle Wrapper 不会“每次启动都重新获取发行包”——它只在本地缓存缺失对应版本时才下载。如果你观察到反复下载 gradle-7.6-all.zip 或类似文件，说明缓存未命中或被破坏，根本原因通常出在路径、权限、网络代理或配置冲突上。
为什么 gradle-wrapper.properties 指向的包总也下不完
真正卡住的位置不是构建阶段，而是 gradlew 启动初期的分发包（distribution）拉取环节。它会按 gradle/wrapper/gradle-wrapper.properties 里的 distributionUrl 去请求 ZIP 包，比如：
distributionUrl=https\://services.gradle.org/distributions/gradle-7.6-all.zip
这个 URL 默认走国外服务器，国内直连大概率超时或极慢。常见现象包括：
- 终端卡在
Downloading https://services.gradle.org/...十几分钟不动 - 报
SocketTimeoutException或ConnectException - 下载完但校验失败，自动重试（因 SHA256 不匹配）
这不是 Wrapper 机制的问题，而是网络可达性问题。别改 Wrapper 逻辑，直接换源或离线部署。
用腾讯云镜像源却没生效？检查这三处覆盖点
init.gradle 放在 ~/.gradle/ 下是全局生效的，但它只影响依赖仓库（mavenCentral() 等），不影响 Wrapper 自己下载 gradle-*.zip。Wrapper 的下载行为完全由 gradle-wrapper.properties 控制，和 repositories{} 无关。
所以以下操作无效：
- 在
~/.gradle/init.gradle里写allprojects { repositories { maven { url 'https://mirrors.cloud.tencent.com/...' } } } - 在
settings.gradle里配dependencyResolutionManagement—— 这管的是项目依赖，不是 Gradle 本体
真正要改的只有：gradle/wrapper/gradle-wrapper.properties 中的 distributionUrl。可替换为：
distributionUrl=https\://mirrors.cloud.tencent.com/gradle/gradle-7.6-all.zip
注意：腾讯云镜像站实际提供 Gradle 分发包，但路径需确认是否存在（部分镜像站只同步了 Maven 仓库，不包含 Gradle ZIP）。推荐优先使用清华源：https://mirrors.tuna.tsinghua.edu.cn/gradle/。
缓存目录被清空或权限异常导致重复下载
Wrapper 下载完成后，会解压到 ~/.gradle/wrapper/dists/ 下的子目录，例如：
~/.gradle/wrapper/dists/gradle-7.6-all/xxxxxx/gradle-7.6/
如果该路径被手动删除、磁盘空间不足、或 IDE 以不同用户身份运行（如 sudo 启动 Android Studio），就无法复用已有解压结果，每次都会重下重解。
验证方式很简单：
- 执行
ls -l ~/.gradle/wrapper/dists/，看目标版本目录是否存在且非空 - 检查该目录 owner 是否和当前用户一致（
ls -ld ~/.gradle/wrapper/dists/） - Android Studio 若通过桌面快捷方式启动，有时会绕过 shell 的
GRADLE_USER_HOME设置，导致缓存写到错误位置
解决办法：统一设置环境变量 GRADLE_USER_HOME=$HOME/.gradle，并在 IDE 的 Help → Edit Custom VM Options 或启动脚本中确保它生效。
新建项目仍提示下载？因为新项目自带默认 distributionUrl
Android Studio 新建项目时，会自动生成一套标准 Wrapper 配置，默认仍是 services.gradle.org。你改过的老项目不会传染给新项目。
有两个务实选择：
- 新建后立刻编辑
gradle/wrapper/gradle-wrapper.properties，把distributionUrl替换为国内镜像地址（最直接） - 提前准备一个模板项目，含已替换好的 Wrapper 配置和预下载的
gradle-*.zip，后续新建时复制粘贴（适合团队）
不要指望 init.gradle 或 IDE 全局设置能接管 Wrapper 下载——它的行为是硬编码在 gradle-wrapper.jar 里的，只认自己的 properties 文件。
