简介：Gradle 5.6.4 完整发行包（all 版）是面向 Java 与 Android 开发者的构建工具资源，适合需要离线安装、快速搭建开发环境或学习新版特性的用户。压缩包共两千个文件，主要包含 Java 源码、HTML 帮助文档、Gradle 与 Kotlin 脚本、Groovy 文件、jar包以及若干可执行代码，整体大小约一百三十四兆字节。该版本着重优化了 Groovy 编译速度，新增 Java 测试夹具插件，并强化多项目构建中的插件版本管理，能明显缩短构建等待时间；同时，包内附带了完整的 API文档、示例项目与扩展点定义，便于开发者查阅和二次开发。目前已有三千八百八十六人学习下载。解压后无需联网安装，即可直接调用其中的可执行文件、库与示例代码，完成项目的构建、测试与打包，适合正在使用 Gradle 5.x 的团队或个人快速上手，也适用于 CI/CD 离线部署场景。 如果你跟我一样，曾经盯着 Android Studio 底部的构建进度条，看它在Downloading gradle-5.6.4-all.zip这一栏卡了十几分钟，然后等来一个Could not install Gradle distribution from...的报错，这篇文章大概率能帮你少走几圈。
gradle-5.6.4-all.zip 的下载问题几乎成为很多老项目开发者的共同记忆。不少项目并不是你想用它，而是 Android Gradle Plugin 3.6.x 锁定了这个 Gradle 版本，Flutter 旧模板也用得很广；无论出于什么原因，只要 wrapper 里写的 URL 是它，构建就绕不开这一关。这篇博文会从版本兼容关系讲起，把镜像加速、手动放置 zip、wrapper 配置、常见报错排查这整条链路完整过一遍，适合正被 Gradle 下载问题卡住的 Android 开发者、Flutter 开发者，也适合维护 Jenkins 打包环境的同学。
1. gradle-5.6.4 的兼容关系：先搞清楚你凭什么在用这个版本
1.1 年份很旧，但访问量居高不下
Gradle 5.6.4 是 5.6 系列后期的一个修复版本，发布时间离现在已经好几年了，但它依然是很多老项目里gradle-wrapper.properties锁定的版本。原因不复杂：Android Gradle Plugin 3.6.x 的基线版本就是 Gradle 5.6.4，AGP 3.6.0 起要求 Gradle 最低为 5.6.4。所以早期从 Android Studio 3.5、4.0 一路带上来的项目，很多都把distributionUrl固定成了gradle-5.6.4-all.zip。
升级 AGP 看着只是改一行版本号，实际要面对构建脚本兼容性、资源命名规则、依赖传递行为这些变化，很多人权衡之后选择继续留在老版本。这个选择本身没有对错，只是意味着你每次换了电脑、清了缓存或者换 CI 节点时，都得先把那个 zip 稳稳定到本地。
1.2 all 与 bin，差的不只是体积
从下载地址到 wrapper 配置，你经常会看到-all和-bin两种后缀。all 是完整发行包，包含 Gradle 源码、文档、样例，压缩包体积在 140MB 左右；bin 只保留运行所需的二进制，体积小一些。项目里到底该用哪个，取决于模板初始化和你的使用习惯：Android Studio 自动生成的 wrapper 有相当一部分用-all，方便开发者在 IDE 里直接查看 Gradle 内部实现；如果你只是跑构建，换-bin能省下一点下载时间。
不过我要提醒一句，改后缀前先确认项目里没有依赖源码阅读的习惯。有些编译问题需要点进 Gradle 源码去排查，那时候手边没有-all包就比较被动。我的原则是：wrapper 原本写的什么就用什么，下载提速靠镜像解决，而不是靠换包类型。
2. 官方源为什么这么慢：从 wrapper 触发到超时重试的完整过程
2.1 wrapper 是怎么把 zip 拉下来的
执行./gradlew或gradlew.bat时，Gradle Wrapper 会先读取gradle/wrapper/gradle-wrapper.properties，检查GRADLE_USER_HOME（默认是~/.gradle）下的wrapper/dists缓存里是否已有匹配的发行包。没有的话，它就会按照distributionUrl指向的地址去下载，下载完成后解压到以 URL 哈希命名的子目录。
这个目录结构常常让人摸不着头脑，比如~/.gradle/wrapper/dists/gradle-5.6.4-all/xxxxxx/，那串xxxxxx是根据 URL 算出来的哈希。换句话说，换一个镜像 URL，对应目录就会不一样。这就是为什么很多人明明已经下载过官方 zip，把distributionUrl改成镜像后还是重新下了一遍——两者是不同缓存目录，Gradle 不会认为它们等价。
2.2 卡住、超时、失败重试的恶性循环
从官方services.gradle.org拉取这个大文件时，不同网络环境下速度差距非常大，快的时候几分钟结束，慢的时候几十 KB/s，高峰期还容易出现连接重置。社区里一大堆Could not install Gradle distribution from 'https://services.gradle.org/distributions/gradle-5.6.4-all.zip'报错，绝大多数都在这一步出的问题。
最麻烦的是失败后重试：Gradle 的断点续传并不总是可靠，中断后残留的.part文件可能让下次下载又从零开始，甚至反复在同一个地方失败。所以碰到超时，我建议先把 dists 下对应目录里的.part和.lck文件清理干净，再考虑换源或换工具。这个习惯能帮你省掉很多无意义的重复等待。
3. 三种实测有效的加速方案：镜像替换、手动放置、脚本复用
3.1 方案一：腾讯云镜像替换 URL
以gradle-5.6.4-all.zip为例，把gradle-wrapper.properties里的distributionUrl改成：
https://mirrors.cloud.tencent.com/gradle/gradle-5.6.4-all.zip这是我日常用得最多的方案。腾讯云镜像的 Gradle 目录结构跟官方保持一致，版本号和文件命名都不变，直接替换这一行，重新执行gradlew，就能从镜像拉取。实测下来速度稳定性比官方源好很多，尤其在大版本文件下载上，基本不会出现那种十几分钟卡着不动的情况。
3.2 方案二：华为云镜像备选
如果腾讯云镜像偶尔抽风，可以切换到华为云：
https://mirrors.huaweicloud.com/gradle/gradle-5.6.4-all.zip地址规律相同，替换文件后缀即可。平时也可以直接在浏览器里输入上面的地址，把 zip 下载到本地备用。遇到公司内网或离线环境，这个方式特别有用——至少你能先拿到文件，再想办法把它放进 Gradle 的缓存目录。
3.3 方案三：手动下载 zip 放进缓存目录
手动放置需要注意目录匹配。第一次执行gradlew时，Gradle 会在~/.gradle/wrapper/dists/gradle-5.6.4-all/下创建对应的哈希目录，但这个目录是下载启动之后才生成的。如果你连第一次下载都没跑起来，目录可能还不存在。
实际操作中我的做法是：先执行一次gradlew，允许它创建好目录并开始下载，然后 Ctrl+C 中断（或者等它超时），再把手动下载好的 zip 拷进刚生成的哈希目录。下一次执行时，Gradle 看到 zip 存在就会自动校验、解压，不再重复下载。如果目录里已经有残留的.part文件，记得先删掉，不然 Gradle 可能认为下载任务未完成，又从头开始。
3.4 脚本方式批量下载、批量复用
对于多台机器或 CI 环境，可以先在能正常下载的机器上下载好 zip，再用脚本按目录结构丢过去。Windows 下可以用 PowerShell 创建目录再复制文件，macOS/Linux 下用mkdir -p加cp即可。核心是保证目录结构与目标机器上distributionUrl对应的哈希目录一致，Gradle 就不会在多环境里重复下载。
4. wrapper 配置细节与本地缓存目录拆解
4.1 gradle-wrapper.properties 每个参数的含义
先看一个典型的配置：
distributionBase=GRADLE_USER_HOME distributionPath=wrapper/dists zipStoreBase=GRADLE_USER_HOME zipStorePath=wrapper/dists distributionUrl=https\://mirrors.cloud.tencent.com/gradle/gradle-5.6.4-all.zipdistributionBase和distributionPath决定 Gradle 发行包解压后放在哪。zipStoreBase和zipStorePath决定下载的 zip 临时存放在哪。GRADLE_USER_HOME默认在用户目录的.gradle下，也可以设置环境变量把它迁移到别的盘或共享目录。
我见过不少团队把所有工程的gradle-wrapper.properties统一改成镜像地址，而且只改distributionUrl，其他参数保持默认。这个做法对老项目最友好，因为不会改变 Gradle 查找缓存的路径逻辑，切换成本最低。
4.2 缓存目录的哈希规则
Gradle 的 dists 目录树是以“gradle-版本-bin/all + 哈希子目录”来组织的。哈希值由distributionUrl计算而来，所以同一个gradle-5.6.4-all.zip，用官方 URL 和用镜像 URL 会各自生成独立的缓存目录。想要复用本地已有的 zip，就得保持distributionUrl写法完全一致。
这也是很多新手手动放置 zip 失败的根源：放错目录，Gradle 会当作没看见，重新开始下载。所以如果你在D:\gradle-dist或者~/downloads里已经存了 zip，不要只把它随便扔到~/.gradle/wrapper/dists/根目录，必须进到具体版本对应的哈希子目录里才有效。
4.3 多工程共享缓存的实际操作
如果本地多个工程都用同一个 Gradle 版本、同一个 URL，它们会共用同一个解压目录，不会重复下载。我会在gradle.properties或环境变量里统一配置GRADLE_USER_HOME，比如指向D:\gradle-home，让多个工程共用同一个 Gradle 用户目录。这样缓存复用率高，也方便整体备份。
如果团队使用 Jenkins，我建议在 Jenkins 节点上固定好GRADLE_USER_HOME，第一次构建时把镜像源和依赖缓存都准备好，后续构建会快很多。否则每个节点都从头拉官方源，不仅慢，还容易把构建超时时间耗尽。
5. 高频报错排查：从 socket timeout 到 cache corrupt 的完整链路
5.1 Could not install Gradle distribution from ... + socket timeout
这个报错信息本身就是从官方 URL 拉取失败。排查链路我一般分三步走：
- 看
gradle-wrapper.properties里的distributionUrl是否能在浏览器里直接访问。 - 把 URL 换到腾讯云或华为云镜像。
- 如果换到镜像还是不行，检查本机代理和防火墙设置，确认没有拦截大文件下载。
网络问题确认解决后，清理 dists 下对应目录里的.part文件再重试。我实测下来，这个报错九成都是下载中断导致的，换成镜像后基本一次通过。
5.2 Gradle's dependency cache may be corrupt
这个报错常见于网络中断后重新构建，~/.gradle/caches里的依赖缓存状态不一致。处理方式通常是关闭 IDE 后删除~/.gradle/caches（注意不是删除整个.gradle），然后重新构建，让 Gradle 重新下载依赖。
如果项目里已经配有本地 Maven 仓库或镜像仓库，可以顺便配置 offline 模式或者仓库地址，避免依赖重复下载和缓存再次损坏。删除缓存目录确实有点“粗暴”，但这是解决 cache corrupt 最直接有效的办法，比你手动去翻损坏的 artifacts 要省心得多。
5.3 Gradle version incompatible with Gradle JVM version
这种报错通常是 Gradle 版本和 JDK 版本不匹配。Gradle 5.6.4 支持的是 Java 8 到 Java 12，如果你在 IDE 里把 Gradle JVM 切到 Java 17 甚至更高版本，就会看到类似The project's Gradle version 6.7.1 is incompatible with the Gradle JVM version的提示。
解决方向不是急着改 Gradle 版本，而是把 Gradle JVM 切回 Java 8 或 Java 11，或者升级 Gradle 版本来配合新 JDK。这里我建议先看清楚项目 AGP 版本再动 Gradle 版本，因为 AGP 和 Gradle 是绑定关系，只升 Gradle 可能引发连锁问题。
5.4 Flutter 项目提示 apply script 方式
Flutter 项目的 Android 模板有一段时期喜欢在android/build.gradle里用apply script方式加载flutter.gradle，新版 Flutter 已经要求改用 plugins DSL。看到类似you are applying flutter's main gradle plugin imperatively using the apply script的提示，需要按新模板改写成 `plugins { id("com.flutter.gradle.
本文还有配套的精品资源，点击获取
