Gradle Wrapper 下载失败怎么办：gradlew 卡在 Downloading、超时、校验失败与代理配置全解

克隆一个 Java 或 Android 项目，执行 ./gradlew build 或在 Android Studio 里点「Sync Project」，终端第一行显示「Downloading https://services.gradle.org/distributions/gradle-8.7-bin.zip」，后面的进度点走了几个就停住。等上十几分钟，最后抛出「Exception in thread "main" java.net.SocketTimeoutException: Read timed out」或者「Could not install Gradle distribution from ...」。有时下载看似完成了，却又报「Verification of Gradle distribution failed!」。

这一步失败的原因很集中：Wrapper 要从 services.gradle.org 下载一个一百多 MB 的压缩包，这个地址会再跳转到下载服务器，任何一段连接不稳都会中断；中断后留在缓存目录里的半截文件和锁文件，又会让下次执行直接报错或卡住。Wrapper 下载完成之后，Gradle 才开始从 Maven Central、Google Maven 和插件门户拉依赖，那是另一段问题。先把 Wrapper 这一步搞定，后面才有意义。

Wrapper、本地 Gradle 与依赖下载的区别

官方推荐所有项目都用 Wrapper，因为它保证了每个人用同一版本的 Gradle 构建。代价是每个新版本都要下载一次。如果报错里出现的是依赖坐标而不是 gradle-x.x-bin.zip，说明 Wrapper 已经装好了，问题在依赖下载阶段，处理方法见文末的分工部分。判断方法很简单：看报错里有没有 gradle-wrapper 或 distribution 字样，有就是 Wrapper 阶段，没有就往后找。

从卡住到构建成功：分步操作

• 第一步：先把网络线路准备好。安装刺猬VPN，自定义用户名和密码注册，不需要邮箱和手机号，连上后先用浏览器打开 services.gradle.org/distributions，确认能看到版本列表，再回到终端。免费节点永久免费、不限流量、不限速，适合先判断是不是网络问题；
• 第二步：查看项目要的版本。打开项目里的 gradle/wrapper/gradle-wrapper.properties，distributionUrl 一行写着要下载的版本，例如 gradle-8.7-bin.zip，记下版本号；
• 第三步：清理残留文件。进入用户目录下的 .gradle/wrapper/dists，找到对应版本的文件夹，里面有一串哈希命名的子目录，如果存在以 .part 结尾的半截文件或 .lck 锁文件，整个版本文件夹删掉；Windows 路径是 C:\Users\用户名\.gradle\wrapper\dists；
• 第四步：给 Gradle 配置代理。Wrapper 是 Java 程序，不读 HTTPS_PROXY 环境变量，要在用户目录下 .gradle/gradle.properties 写入 systemProp.http.proxyHost、systemProp.http.proxyPort、systemProp.https.proxyHost、systemProp.https.proxyPort，并用 systemProp.http.nonProxyHosts 排除 localhost；
• 第五步：延长超时。Gradle 7.6 以后可以在 gradle-wrapper.properties 里加 networkTimeout=60000，单位是毫秒，网络慢时不至于过早放弃；
• 第六步：重新执行 ./gradlew --version。只做下载与解压，不触发构建，能最快验证 Wrapper 这一步是否成功；看到版本信息就说明装好了；
• 第七步：如果仍然失败，手动下载。用浏览器下载同名压缩包，放进第三步那个哈希目录里，不要解压，再执行 gradlew，它会识别已存在的压缩包并自行解压；
• 第八步：Android Studio 用户在「Settings」「Build, Execution, Deployment」「Build Tools」「Gradle」里确认「Gradle user home」与命令行一致，然后点「Sync Project with Gradle Files」。

按报错的那一行排查

• 停在 Downloading 后面的进度点不动：到下载服务器的连接中断，确认线路后删除半截文件重试；
• SocketTimeoutException: Read timed out：连接建立了但数据迟迟不来，加大 networkTimeout，换延迟更低的节点；
• ConnectException: Connection timed out 或 Connection refused：根本连不上下载地址，检查 gradle.properties 里的代理主机和端口是否正确；
• Verification of Gradle distribution failed：下载的压缩包与 distributionSha256Sum 不一致，文件损坏或下载到了错误页面，删掉重下，不要删掉校验值；
• Timeout waiting to lock distribution：另一个 Gradle 进程正在下载同一版本，或上次中断留下了锁文件，执行 gradlew --stop 后删除 .lck 文件；
• Could not find or load main class org.gradle.wrapper.GradleWrapperMain：项目里的 gradle-wrapper.jar 缺失，通常是被 .gitignore 排除了，从别处恢复这个文件或用本机 Gradle 执行 gradle wrapper 重新生成；
• PKIX path building failed：证书校验失败，常见于公司网络或杀毒软件扫描 HTTPS，关闭扫描或把证书导入 JDK 的信任库。

官方下载、镜像与手动安装怎么选

改 distributionUrl 指向镜像能立刻解决下载问题，但这一行会被提交进仓库，团队其他成员和持续集成也会跟着用镜像，镜像停更或缺版本时所有人一起失败。更稳妥的做法是项目文件保持官方地址，各人在自己的 gradle.properties 里配代理。刺猬VPN支持按域名的智能分流，可以只让 gradle.org 相关域名与 Maven 仓库走线路。实际可用性取决于当前网络环境。

缓存目录的结构与清理

Gradle 的所有下载都在用户目录下的 .gradle 文件夹里，可以通过 GRADLE_USER_HOME 环境变量改到别的磁盘。其中 wrapper/dists 放各个版本的 Gradle 本体，caches 放依赖与构建缓存，daemon 放后台进程的日志。时间久了这个文件夹会膨胀到十几 GB，旧版本的 Gradle 本体可以放心删除，下次哪个项目用到会重新下载。

清理时要先执行 gradlew --stop 停掉后台进程，否则文件被占用删不掉，或者删到一半留下更难处理的残留。只想解决某个版本的下载问题，就只删 dists 下那一个版本的文件夹，不要整个 .gradle 一起删，否则所有项目的依赖都要重新下载，网络不好时会把一个小问题放大成一下午的等待。

C 盘空间紧张的 Windows 用户，可以把 GRADLE_USER_HOME 设到 D 盘，然后在 Android Studio 里同步修改「Gradle user home」。改完之后旧位置的缓存不会自动迁移，可以手动移动过去，也可以让它重新下载。

Windows、macOS 与 IDE 之间的差异

Windows 上执行的是 gradlew.bat，macOS 与 Linux 上执行的是 ./gradlew。从 Windows 拷到 macOS 的项目，gradlew 可能丢了可执行权限，报「Permission denied」，执行一次 chmod +x gradlew 即可。反过来，在 Windows 上用 Git 检出时如果换行符被转换，gradlew 在 Linux 构建机上会报找不到解释器，仓库里最好用 .gitattributes 把它固定为 LF。

IDE 与命令行不共用配置也是常见坑。Android Studio 和 IntelliJ IDEA 有自己的 HTTP 代理设置，同步项目时 IDE 会把这份设置写进用户目录的 gradle.properties，可能覆盖你手动写的代理行；IDE 里配的 JDK 也可能与终端的 JAVA_HOME 不同，导致同一个项目在 IDE 里能同步、在终端里报版本错误。排查时先在终端执行 gradlew --version，看它用的是哪个 JDK，再对照 IDE 设置里的「Gradle JDK」。

插件门户与仓库顺序

Wrapper 下载完成、构建开始后，第一批请求往往发给插件门户 plugins.gradle.org，用来解析 settings.gradle 或 build.gradle 里 plugins 代码块声明的插件。这里失败时报的是「Plugin [id: '...'] was not found in any of the following sources」，看起来像插件名写错了，其实多半是门户连不上。

settings.gradle 里的 pluginManagement 与 dependencyResolutionManagement 两个代码块决定了从哪些仓库、按什么顺序查找。顺序靠前的仓库连不上时，Gradle 会等它超时才去问下一个，构建因此变得极慢。确认线路能访问 google、mavenCentral 与 gradlePluginPortal 三个仓库后，按 Android 项目的惯例把 google 放在第一位，不要随手加一堆早已停止服务的第三方仓库。

离线模式与后台进程的小技巧

• Wrapper 与依赖都下载过一次之后，网络不好时可以加 --offline 参数构建，Gradle 只用本地缓存，不再联网检查更新；缺什么依赖会直接报错，不会卡着等超时；
• 改完 gradle.properties 里的代理后，先执行 gradlew --stop 停掉旧的后台进程，否则新的配置不会生效，旧进程仍按原来的设置联网；
• 怀疑缓存的依赖损坏时，用 --refresh-dependencies 强制重新检查，而不是删掉整个缓存目录；
• 想看清卡在哪个请求上，加 --info 或 --debug 参数，日志里会打印每一个正在下载的地址，复制出来在浏览器里打开，就能判断是哪个主机不通。

持续集成与多人协作

持续集成的机器每次都是干净环境，Wrapper 每次都要重新下载，最容易在这一步失败。主流平台都支持缓存目录，把 .gradle/wrapper 与 .gradle/caches 加入缓存配置，键值用 gradle-wrapper.properties 与构建脚本的哈希，版本不变就不必重复下载。构建机器的代理配置写在环境变量 GRADLE_OPTS 里，用 -Dhttps.proxyHost 与 -Dhttps.proxyPort 传入。

团队协作时，gradle-wrapper.jar、gradlew、gradlew.bat 与 gradle-wrapper.properties 四个文件都要提交进仓库，缺一个都会让别人执行失败。升级 Gradle 版本时用 ./gradlew wrapper --gradle-version 新版本号，它会同时更新属性文件和 jar，并在属性文件里写入新的校验值，比手动改版本号更可靠。

和其他构建与依赖工具的分工

Wrapper 装好之后，构建会开始从 Maven Central 拉依赖，这时报的是「Could not resolve」加依赖坐标，处理思路与 Maven、NuGet 相通，见 Maven Central 与 NuGet 下载失败。仓库顺序、镜像与代理的配置都在那一篇里。

Android 项目还要同时处理 SDK 组件的下载，sdkmanager 拉不下清单、许可证没接受、cmdline-tools 目录放错，都会在同步时报错，但和 Gradle 本身无关，见 Android SDK 下载失败排查。三段各自验收：gradlew --version 成功、sdkmanager --list 成功、依赖解析成功。

常见报错速查表

高频问答

• 问：设置了系统代理为什么 Gradle 还是超时？答：Gradle 是 Java 程序，不读系统代理与 HTTPS_PROXY，要在 gradle.properties 里单独配置；
• 问：能把 Wrapper 换成本机 Gradle 吗？答：能用，但版本可能与项目不匹配，团队项目建议保持 Wrapper；
• 问：手动下载的压缩包要解压吗？答：不用，放进对应哈希目录，gradlew 会自己解压；
• 问：bin 和 all 两种包有什么区别？答：all 多了源码与文档，方便 IDE 跳转，体积更大，没有特殊需要用 bin；
• 问：改 distributionUrl 为镜像要提交吗？答：不建议，会影响团队与持续集成，个人用代理配置更稳；
• 问：免费节点够用吗？答：够判断网络问题，首次下载 Gradle 与依赖建议用时长套餐，有效期内不限流量、不限速。

把 Wrapper 这一步一次做好

Gradle Wrapper 下载失败，十有八九是到 services.gradle.org 的连接不稳，加上中断后的残留文件让问题反复出现。先确认浏览器能打开下载地址，再删残留、配代理、加超时，用 gradlew --version 单独验证，实在不行就手动下载放进缓存目录。Wrapper 通过后再处理依赖与 SDK，每一段单独验收。

刺猬VPN采用 HTTPS+AES 加密传输，自定义用户名和密码即可匿名注册，不需要邮箱和手机号；免费节点永久免费、不限流量、不限速；时长套餐有效期内不限流量、不限速，客户端支持按域名与 IP 的智能分流和断线保护，一个账号可在多台开发机上使用。下载能否顺利完成取决于当前网络环境。