简介：Gradle 5.6.2 是 Java 生态中广泛使用的构建自动化工具，该 zip 为官方 all 发行版，适合需要离线安装、本地构建或快速切换版本的开发者、DevOps 工程师。此版本重点修复了 Gradle 5.6.1 中的两个已知问题：一是 Gradle 5.6 及以上版本生成的 .classpath 文件出现重复条目，干扰 Eclipse 等 IDE 的项目导入；二是使用 Worker API 并启用进程隔离的任务出现内存泄漏，影响长时间、高并发的构建任务。因此对依赖 Eclipse 开发或维护大型模块化构建的团队，升级到该版本能带来更稳定的构建体验。压缩包整体约 134.42MB，内含 Gradle 运行脚本、核心类库与功能模块，all 发行版不依赖额外网络下载，可满足单机或 CI 环境部署需要。目前已有 419 人浏览/下载，适合正在排查构建异常或希望固定使用 5.6.2 版本的开发者直接取用。 做 Android 和 Flutter 开发的，应该没人没被 gradle-5.6.2-all.zip 卡过。新电脑、新同事、新 CI 节点，项目一 sync，底部状态栏就停在 Downloading https://services.gradle.org/distributions/gradle-5.6.2-all.zip，百分比半天不动一下。不是网络配置有问题，是官方那个发行版服务器对国内连接质量本来就这个德行，一百多兆的文件，运气差能下一整天，更气人的是下一半断掉，缓存的半截文件还占着坑，重来一遍还是从 0% 开始。这篇文章就冲着这个痛点来的：把 gradle-5.6.2-all.zip 的快速下载、镜像换源、离线落盘、一次配置全家桶全部讲清楚，Android Studio 新手和 CI 维护的老手都能照着抄。

1. 为什么全网都在找 gradle-5.6.2-all.zip：版本锚点与 all 包的真相

1.1 5.6.2 是 Flutter 老模板和 AGP 3.6 的版本锚点

先解释一个很多人困惑的点：gradle-5.6.2 不是什么新版本，2019 年就发布了，为什么现在还有大量的人在搜它？因为决定 Gradle 版本的从来不是"你用的东西有多新"，而是项目里另外两个软件的版本：Flutter SDK 和 AGP（Android Gradle Plugin）。

先说 Flutter。2020 年前后的 Flutter stable 分支（大概 1.17 到 1.22 这个区间），新建工程的 android/gradle/wrapper/gradle-wrapper.properties 里，distributionUrl 默认指向的就是 gradle-5.6.2-all.zip。那个年代大量 App 项目都用这套模板初始化，模板一旦写死，后面接手的每个人打开项目都要面对这个固定链接。

再说 AGP。Android 工程的 Gradle 版本要满足 AGP 的最低要求，AGP 3.6.x 最低需要 Gradle 5.6.4，而 AGP 3.5.x 时代很多项目直接就把 Gradle 钉在 5.6.2。老项目不动 AGP，Gradle 就不会跟着升。所以 5.6.2 成了一个庞大的"历史锚点"，新建项目早不用它了，但存量项目绕不开，这就是它被反复搜索的根本原因。

1.2 -all 与 -bin 的区别：IDE 提示和代码跳转都靠它

Gradle 发行包有 -bin、-all、-src 三种后缀。-bin 只有运行时文件，体积约 80MB；-all 额外打包了 Gradle 的源码和文档，体积 100 多 MB；-src 是纯源码包，日常用不到。

日常命令行构建用 -bin 完全没问题，但 Flutter 模板和 Android Studio 坚持用 -all 是有原因的：IDE 的 Gradle DSL 解析、build.gradle 里的方法跳转、插件 API 补全，都需要本地有 Gradle 源码文件，缺了源码，编辑器里点进去全是 "Sources not found"，很影响排查问题。所以别贪图 bin 包小就去替换 distributionUrl，主要用 IDE 开发的话，老老实实下 all。bin 和 all 下哪个，不只是体积问题，直接关系到你的开发体验。

2. 把 distributionUrl 换到国内镜像：一劳永逸的下载方案

2.1 官方源慢在哪

services.gradle.org 部署在海外，国内直连的链路质量非常不稳定。下载大文件时，常见表现是：连接能建立，速度常年徘徊在几十 KB，过一会儿 TCP 连接被掐断，wrapper 自动重试，重试几次后抛出一个 "Could not install Gradle distribution" 就整体失败。更麻烦的是，失败后下载到一半的临时文件不会自动清理，下一次启动又从 0 开始，给人的感觉就是"永远在下载"。

这道题的正解不是调超时参数，也不是反复重试，而是彻底绕开官方服务器。国内几家公有云对 Gradle 发行版做了整库同步，速度和稳定性都碾压直连。

2.2 腾讯云 / 华为云镜像地址与下载方式

目前还在稳定维护 Gradle 发行版镜像的公有云，我实际用下来主要推荐两个：

镜像源	根地址	gradle-5.6.2-all.zip 直链
腾讯云	https://mirrors.cloud.tencent.com/gradle/	https://mirrors.cloud.tencent.com/gradle/gradle-5.6.2-all.zip
华为云	https://repo.huaweicloud.com/gradle/	https://repo.huaweicloud.com/gradle/gradle-5.6.2-all.zip

这两个链接可以直接丢进浏览器，或者用命令行工具拉取：

wget https://mirrors.cloud.tencent.com/gradle/gradle-5.6.2-all.zip

实测下来，腾讯云挂 CDN，在多数宽带和校园网下都能跑满带宽；华为云的目录完整度更高，有些内网环境反而更顺。选一个你本机速度快的就行。下载完先核对一下体积：官网标注 gradle-5.6.2-all.zip 大约 103MB，如果下载结果和标注差得太多，直接删掉重下，别省这一步，半截包后面会坑你。

2.3 改 gradle-wrapper.properties：让项目直接从镜像拉包

如果你不想手动下载，希望项目自己就把包拉下来，那就改项目里的 gradle/wrapper/gradle-wrapper.properties：

distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
distributionUrl=https\://mirrors.cloud.tencent.com/gradle/gradle-5.6.2-all.zip
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists

注意 properties 文件里冒号要转义成 :，别删。改完重新 sync，wrapper 的下载源就变成腾讯镜像了。这个方案对 Flutter 工程特别实用，因为 flutter 命令每次构建都会先触发 gradle wrapper 的检测，distributionUrl 指向国内源之后，构建启动阶段不再卡网络，整个流程顺滑很多。

2.4 下载完整性校验：SHA-256 兜底

换源下载之后最好做一次校验，尤其是你之前被半截包坑过。Gradle wrapper 本身就支持在 properties 里加哈希校验：

distributionSha256Sum=<官方页面提供的64位哈希>

校验命令在 Linux/macOS 上是：

sha256sum gradle-5.6.2-all.zip

Windows PowerShell 用：

Get-FileHash gradle-5.6.2-all.zip -Algorithm SHA256

对比官方页面给出的哈希值，一致就说明文件没问题。加了 distributionSha256Sum 之后，wrapper 每次都会重新计算哈希，文件损坏会直接报错而不是继续往下走，这对定位"莫名其妙的构建失败"很有帮助。

3. 离线包塞进 gradle 缓存的正确姿势：dists 目录详解

3.1 wrapper 的目录结构与 hash 目录

gradle wrapper 的下载缓存统一放在 GRADLE_USER_HOME（默认 ~/.gradle）下面，结构是：

~/.gradle/wrapper/dists/gradle-5.6.2-all/<hash目录>/gradle-5.6.2-all.zip
~/.gradle/wrapper/dists/gradle-5.6.2-all/<hash目录>/gradle-5.6.2/.ok

中间那一长串 hash 目录不是随机生成的，它由 distributionUrl 的字符串内容计算而来。同样的官方地址在全世界任何一台机器上算出来的 hash 都一样，但如果你把 distributionUrl 改成腾讯镜像，hash 立刻变。这意味着：想把 zip 手动放进去让 wrapper 跳过下载，必须保证 hash 目录和项目里实际使用的 distributionUrl 是对应的。

3.2 三步手动放包，让 wrapper 跳过网络

之前看过很多教程说"把 zip 丢进 dists 就完事"，实际上里面有个前提：Gradle 解压完之后会写一个 .ok 标记文件，判断发行版是否安装完成的条件是 .ok 存在，而不是 zip 存在。正确的手动放包流程是：

1. 先跑一次构建，让它把 hash 目录创建出来；或者直接看报错信息，Gradle 会把目标路径完整打印出来。
2. 把下载好的 zip 放进 hash 目录，解压出 gradle-5.6.2 文件夹。
3. 在 gradle-5.6.2 文件夹里新建一个空文件，命名为 .ok。
4. 重新 sync。

Gradle 检查到 .ok 标记后，会认为发行版已经安装完成，完全不走网络。这套做法的好处是不用改项目里的 distributionUrl，团队里其他人继续用官方地址也不受影响，只有你自己这台机器用本地缓存。

注意：如果之前下载失败过，hash 目录里可能残留 .part、 .lck 之类的临时文件，手动放包前务必清掉，否则可能触发校验异常。

3.3 根治新项目重复下载的问题

"Android Studio 每次新建项目都要重新下载 Gradle" 是高频痛点。原因很简单：不同项目模板用的 Gradle 版本不同，缓存目录按版本隔离，你本地没下载过那个版本的包，sync 自然要现下。根治办法有三个层级：

• 项目层：统一团队的 gradle-wrapper.properties，全部指向同一个版本加国内镜像地址。
• IDE 层：Android Studio 的 Settings → Build, Execution, Deployment → Build Tools → Gradle，选 Use local Gradle distribution，直接指向你已经解压好的本地目录。这样新建项目从 IDE 跑就不走 wrapper 下载。
• 机器层：把整个 ~/.gradle/wrapper 目录打包备份。新机器、新同事入职、CI 从零构建，直接解压恢复，几十个项目秒过 sync。

我自己在团队里一直用第三个方案，性价比最高，一次备份，长期受益。

4. 换源后仍然高频踩的四个 Gradle 报错

4.1 Could not install Gradle distribution from ... 的完整排查链路

报错原文：

Could not install Gradle distribution from 'https://services.gradle.org/distributions/gradle-5.6.2-all.zip'.

这个错几乎都是下载环节挂了，原因可能是超时、断连，或者磁盘里残留了半截 zip。我建议的排查链路固定如下：

1. 打开 ~/.gradle/wrapper/dists/gradle-5.6.2-all/，看是否存在对应的 hash 目录，把里面的临时文件全删。
2. 确认项目的 gradle-wrapper.properties 用的是镜像地址，或者按 3.2 的方法手动放好 zip 加 .ok。
3. 从命令行跑一次 ./gradlew --version 验证 wrapper 能否完成安装，别只依赖 IDE 界面，IDE 有时会把真正的目录路径藏起来。

这个顺序走下来，绝大多数情况到第 2 步就解决了。如果第 3 步还报错，就去检查本地磁盘空间和 JDK 版本。

4.2 Deprecated Gradle features 警告与升级 AGP 的联动

构建结束时如果打印：

Deprecated Gradle features were used in this build, making it incompatible with Gradle 7.0.

这是 Gradle 5.6 在提醒你：项目里某个插件或 build.gradle 脚本用了 5.6 中已标记废弃的 API，强行升到 Gradle 7.0 会直接不兼容。如果暂时不升级，这个警告不影响正常构建，可以忽略。但很多人被这句警告吓到，直接去升 distributionUrl，结果 AGP 版本跟不上，项目反而崩了。

AGP 和 Gradle 版本是绑定的，升级要成对考虑：

AGP 版本	对应最低 Gradle	建议 JDK
3.6.x	5.6.4	JDK 8
4.0.x	6.1.1	JDK 8/11
4.2.x	6.7.1	JDK 8/11
7.x	7.x	JDK 11
8.x	8.x	JDK 17

热搜里那句 "com.android.tools.build:gradle:4.2.0 怎么升级为 AGP"，本质上就是按这张表把 Gradle 和 JDK 一起升，而不是单独改一个版本号。升级时重点看对应版本的 release note 里的 breaking changes，一次性把三个版本对齐，比一个个试省太多时间。

4.3 Flutter 工程的 apply script 报错

如果你在 Flutter 3.x 加新版 AGP 8 的工程里见到：

You are applying Flutter's main Gradle plugin imperatively using the apply script method, which is not supported and will be removed.

这个错和 gradle-5.6.2 的下载完全是两码事，但经常在同一批 Gradle 问题里出现，因为大家搜相关问题时会一起撞见。它的成因是：工程的 settings.gradle 还在用老的 apply script 方式加载 Flutter Gradle 插件，而新版 AGP 要求使用 plugins DSL。修法是按 Flutter SDK 对应版本的迁移说明改 settings.gradle，把 Flutter 插件声明切到 plugin management 区块。

这里提醒一句：碰到这个报错，别去改 distributionUrl、把 Gradle 降回 5.6.2 来"逃避"，新版 AGP 根本不支持那么老的 Gradle，硬降只会引出更多错误。按 Flutter 官方升级流程走一次，反而干净。

4.4 PKIX path building failed 的证书问题

下载 Gradle 时如果报 PKIX 相关错误，很多人第一反应是继续重试，实际上这是本地 JDK 或 IDE 的证书链校验失败，重试一万次也没用。常见诱因是：本地装了抓包工具或安全软件，往系统证书库里塞了自签 CA；或者 JDK 版本太老，cacerts 里缺少新版证书链。

处理办法：优先升级到较新的 JDK，清空 dists 缓存重新下载；如果公司网络有统一上网出口，需要把出口网关的根证书导入 JDK 的 cacerts。这类问题断断续续，但一旦想通是证书而不是网络，排查路径就清晰了。

5. 从 zip 到跑起来的最后一公里：安装配置与工程落地速查

5.1 全局安装 Gradle：解压、环境变量、版本验证

如果你不满足于 wrapper 的按项目缓存，想给整台机器装一个全局 Gradle，步骤如下：

1. 下载 gradle-5.6.2-all.zip，解压到 /opt/gradle/ 或 D:\gradle\。
2. 配置环境变量 GRADLE_HOME 指向解压目录，PATH 里追加 %GRADLE_HOME%\bin（Windows）或 $GRADLE_HOME/bin（Linux 和 macOS）。
3. 终端执行 gradle -v，看到 Gradle 5.6.2 和 JVM 信息就成功了。

全局 Gradle 和 wrapper 不冲突。wrapper 的核心价值是锁定项目版本，全局 Gradle 的价值是命令行调试和临时测试。另外注意，Gradle 5.6.2 需要 JDK 8 或 11 才能跑，用 JDK 17 去跑老 Gradle 会报不兼容错误。

5.2 项目里的 maven 仓库换源与本地仓库生成

Gradle 发行版换源只是第一步，构建时拉 AGP、依赖库走的是 maven 仓库。google() 和 mavenCentral() 在国内同样不快，所以建议把仓库也换成国内镜像：

repositories {
    maven { url 'https://maven.aliyun.com/repository/public' }
    maven { url 'https://maven.aliyun.com/repository/google' }
    maven { url 'https://maven.aliyun.com/repository/gradle-plugin' }
    maven { url 'https://mirrors.cloud.tencent.com/nexus/repository/maven-public/' }
}

这里解释一下：腾讯和华为的 Gradle 发行版镜像解决的是 gradle-X-all.zip 的下载问题；阿里和腾讯的 maven 镜像解决的是项目依赖的下载问题。两个是不同层面的换源，别混为一谈。

另外搜索里有个"让 .gradle 生成本地 maven 和 pom 文件"的需求。很多人想从 gradle 缓存里导出 pom，但 ~/.gradle/modules-2 里的缓存不是仓库结构，导不出完整可用的 pom。正确做法是用 maven-publish 插件：

apply plugin: 'maven-publish'

publishing {
    publications {
        mavenJava(MavenPublication) {
            from components.java
        }
    }
}

然后执行：

./gradlew publishToMavenLocal

这样会在 ~/.m2/repository 下生成标准的 maven 仓库结构，包含 jar/aar 和对应的 pom 文件，之后其他项目直接引 mavenLocal() 就能复用。

5.3 获取签名 SHA1 的两条实用命令

"android gradle 获取 sha1" 也是高频需求，常见于接入地图或支付 SDK 时填写包名和签名。最简单的是用 gradle 自带任务：

./gradlew signingReport

输出里会列出 debug 和 release 各变体的 MD5、SHA1、SHA256。如果只看 debug 签名，可以直接用 keytool：

keytool -list -v -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass android -keypass android

这条命令输出的 SHA1 就是调试签名的指纹，很多 SDK 后台只要求 SHA1 和包名。如果要正式签名的指纹，把 -keystore 换成你的正式 keystore 文件路径就行。稳妥起见，复制时把 SHA1 和 SHA256 一起存下来，免得后续接某个 SDK 又回来翻。

最后说点个人经验。我现在团队里入职装机的第一件事，就是把打包好的整个 ~/.gradle/wrapper 目录拷到新机器，配合全局 Gradle 和 --offline 参数，新人第一天就能正常 sync 不卡下载。gradle-5.6.2-all.zip 这个包往后还会被搜很久，老项目总有老项目的生命周期，学会镜像换源、离线缓存、版本联动这三板斧，比记住某一个下载链接值钱得多。希望这篇文章能帮你把被下载折磨的时间省下来，花在真正该花的地方。

本文还有配套的精品资源，点击获取