简介：这是Gradle 8.0.2完整发行包（all版本），面向Java/Scala开发者与CI/CD工程人员，用于解决Gradle 8.0系列工具链兼容性问题，包括元空间耗尽、JavaCompile自定义编译器失效、Scala 2.13构建失败、远程构建缓存未命中、插件配置状态异常等已知缺陷，是升级或回归验证时的官方补丁。压缩包共11587个文件，包含8399个Java源文件、2380个HTML文档、370个Kotlin脚本、238个JAR组件，以及PNG、JS、CSS等辅助资源，整体约159.92MB，涵盖二进制、源码、API文档和启动脚本，目录组织规范，便于本地离线搭建与查阅。使用该发行包可省去逐条检索补丁说明的时间，直接获得稳定的构建工具基础；内置脚本与文档已按官方发行规范整理，在内网或受限网络环境下亦能快速完成环境配置与问题定位，并支持快速回归验证。目前已有742人学习/下载，关注度较高，可作为选用时的参考热度。 做 Android 的同学应该都有过这种经历：新配的电脑、刚拉的代码，一同步项目就卡在 Gradle 下载那一步，进度条不动，日志里只有一句 "Downloading https://services.gradle.org/distributions/gradle-8.0.2-all.zip"。等上十几分钟，最后等来的可能是 "Could not install Gradle distribution from ..." 或者下载到一半直接超时。gradle-8.0.2-all.zip 这个文件大概 200MB 出头，放在官方 CDN 上，国内直连的速度时好时坏，高峰期基本就是无限重试。这篇文章不聊虚的，就讲怎么把这个文件快速、稳定地搞到本地：镜像换源、离线部署、缓存复用，顺便把升级到 Gradle 8.0.2 之后常见的 AGP 版本、JDK 17、deprecated 警告、Flutter 插件报错这些连带问题一次说清。适合正在被 Gradle 下载折磨的开发者，以及要帮团队搭建统一构建环境的人。

1. 先搞清楚你下载的到底是个什么东西

1.1 -all 版本和 -bin 版本差在哪

Gradle 官方在 services.gradle.org/distributions 下会同时发布 bin、all、src 三种包。bin 是纯二进制，大概 120MB；all 在 bin 的基础上带了完整源码、文档和示例，体积一般在 200MB 出头。对日常构建来说，bin 完全够用，为什么很多项目的 wrapper 偏偏写的是 all？因为 Android Studio 和 IntelliJ IDEA 需要 -all 包才能在 IDE 里跳转到 Gradle 自身的源码，很多团队模板和教程也就默认用了 all 版本。这就导致下载体积直接翻倍，在国内网络环境下更容易失败。

这里插一句，8.0.2 是 8.0 的第二个补丁版，发布时间在 2023 年 3 月中旬。它修复了 8.0 早期版本的一些问题，同时又兼容后续 AGP 8.x 的构建需求，所以在当时被大量项目采用。现在虽然 Gradle 已经往后走了好几个大版本，但老项目里 8.0.2 的身影依然非常多，尤其是那些从 AGP 7 往上升级但还没完全跟上节奏的仓库。

1.2 wrapper 的下载机制是理解所有问题的钥匙

Gradle wrapper 的逻辑其实很简单：读取 gradle-wrapper.properties 里的 distributionUrl，然后检查 GRADLE_USER_HOME（默认是 ~/.gradle）下的 wrapper/dists/gradle-8.0.2-all/{hash}/ 目录。如果有解压好的版本且存在 .ok 完成标记，直接用；否则下载 zip、解压、写标记。整个过程看起来不复杂，但有两个细节特别容易踩坑。

第一个细节：{hash} 目录名是根据 distributionUrl 的完整字符串算出来的。也就是说，你把 URL 从官方地址改成腾讯镜像，哪怕下载的是同一个 gradle-8.0.2-all.zip，wrapper 也会认为这是"另一个版本"，重新下载一份到新的 hash 目录。很多人在本地明明下载过 Gradle，换源后却发现它又开始转圈，就是这个原因。

第二个细节：所谓 "Could not install Gradle distribution from ..." 这个报错，字面意思是"安装失败"，但根因九成是下载失败或校验失败，而不是解压权限问题。排查顺序应该是：URL 可达性 → 网络超时 → checksum 校验，按这个顺序走，基本不会跑偏。

理解了这些，下载问题的三条解决路线就清楚了：改 URL 走镜像、手动放包进缓存目录、直接安装本地 Gradle 绕过 wrapper。下面逐个说。

2. 镜像换源：改一行配置就能提速

2.1 国内可用的镜像站对比

我实际用过的主流光镜像有下面几个：

镜像源	地址模板	稳定性	说明
腾讯云	mirrors.cloud.tencent.com/gradle	高	更新及时，文件完整，推荐首选
华为云	mirrors.huaweicloud.com/gradle	高	速度不错，北方网络环境表现好
阿里云	mirrors.aliyun.com/gradle	中	目录存在但部分版本同步不及时，建议先访问确认
清华 TUNA	mirrors.tuna.tsinghua.edu.cn/gradle	中	教育网内友好

我自己用得最多的是腾讯云，目录全，从老版本到新版本都有，而且文件名和官方保持一致，.sha256 校验文件也在。优先用它，失败就换华为云，两个都试过基本能覆盖绝大多数场景。

2.2 修改 gradle-wrapper.properties

找到项目根目录的 gradle/wrapper/gradle-wrapper.properties，把 distributionUrl 替换成镜像地址：

distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
distributionUrl=https\://mirrors.cloud.tencent.com/gradle/gradle-8.0.2-all.zip
networkTimeout=60000
validateDistributionUrl=true
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists

几个关键注意点：

• distributionUrl 里的冒号必须写成 :，这是 Java properties 的转义规则，反斜杠不能省。我见过有人直接复制浏览器地址导致解析失败的，现象是报 "Malformed URL" 或者下载地址里多个奇怪的字符。
• networkTimeout 单位是毫秒，默认 10000 就是 10 秒。国内网络下 10 秒很容易超时，建议直接调到 60000，给慢速网络留点余地。
• validateDistributionUrl 默认 true，wrapper 下载前会先发一个 HEAD 请求探测 URL 是否可达。如果你在公司内网、代理环境里遇到 "Could not HEAD ..." 或类似报错，先确认是不是这个探测卡住了，可以临时改成 false 验证一下。

改完直接跑 ./gradlew --version，理论上就能看到下载速度有明显变化。腾讯云这种国内节点，跑满带宽很正常，200MB 的包一般一两分钟就完事。

2.3 换源后可能冒出来的两个新问题

第一个是 TLS 证书问题。如果报 SSLHandshakeException，通常是 JVM 的 CA 证书库太旧，不认镜像站的证书链。遇到这个优先升级 JDK，而不是关证书校验，后者等于把安全防线拆了，CI 环境里尤其不能这么干。

第二个是 checksum 校验失败。Gradle 8 默认会对下载的 zip 做 SHA-256 校验，如果镜像上的文件不完整、或者下载过程中被中间设备截断，会报 "Verifying the checksum of the distribution failed"。遇到这个先别急着怀疑网络，直接换个镜像源试试，大概率是源站文件同步出了问题，换源比反复重试效率高得多。

3. 离线部署：彻底不依赖网络的下载方案

3.1 手动往 wrapper 缓存目录放包

如果网络条件实在差，或者公司内网机器根本连不上外网，那就走手动放包路线。操作分四步：

1. 先在能联网的机器上，用浏览器或 curl 把 gradle-8.0.2-all.zip 下载下来。
2. 离线机器上先跑一次 ./gradlew --version，让 wrapper 创建好缓存目录结构。这一步会报下载失败，但目录已经建好了，路径类似 ~/.gradle/wrapper/dists/gradle-8.0.2-all/{hash}/。
3. 把 zip 拷贝进这个 {hash} 目录并解压，确保解压出来的目录名是 gradle-8.0.2-all，与 zip 文件放在同一层。
4. 在该目录下创建一个空文件名为 .ok 的标记文件。Linux/macOS 执行 touch .ok，Windows 用 Git Bash 或直接新建空文件。

完成后的目录结构应该是这样的：

~/.gradle/wrapper/dists/gradle-8.0.2-all/{hash}/
├── gradle-8.0.2-all/
├── gradle-8.0.2-all.zip
└── .ok

.ok 文件是关键。没有它，就算 zip 和解压目录都齐了，wrapper 也会认为"上次没下完"然后重新下载。这个标记文件机制很多人不知道，导致手动放包后依然报下载失败，白折腾半天。还有一点要提醒：{hash} 目录必须是通过实际 URL 生成的，你手动猜一个目录名放进去没用，一定要先跑一次让 wrapper 把目录建出来再操作。

3.2 下载后先做校验，别急着解压

手动下载最怕什么？下到一半的文件被当成完整包。Gradle 8 的 wrapper 本身有校验，但如果走文件协议（file://）或者手动放包，有些场景会绕过校验。稳妥做法是自己先校验一次。

官方每个发行版旁边都有对应的 .sha256 文件，地址是：

https://services.gradle.org/distributions/gradle-8.0.2-all.zip.sha256

拿到期望值后，在本地计算 zip 的 SHA-256 再比对：

Linux/macOS：

sha256sum gradle-8.0.2-all.zip

macOS 上可能没有 sha256sum，用：

shasum -a 256 gradle-8.0.2-all.zip

Windows PowerShell：

Get-FileHash .\gradle-8.0.2-all.zip -Algorithm SHA256

比对一致再解压。不要随便信博客里贴的哈希值，以官方 .sha256 文件内容为准。镜像站一般也会同步这个校验文件，但最终一致性还是以官方为准。

3.3 本地安装 Gradle 并配置环境变量

除了喂给 wrapper，也可以直接把这个 zip 解压成本地 Gradle，供命令行或团队服务器使用。解压到统一位置，比如 Linux 的 /opt/gradle/gradle-8.0.2，Windows 的 D:\tools\gradle-8.0.2。

然后配置环境变量：

export GRADLE_HOME=/opt/gradle/gradle-8.0.2
export PATH=$GRADLE_HOME/bin:$PATH

Windows 就在系统环境变量里新增 GRADLE_HOME，然后在 Path 里加上 %GRADLE_HOME%\bin。验证：gradle -v，能输出版本信息就说明安装成功。

这里多说一句，本地装 Gradle 和项目用 wrapper 并不冲突。wrapper 的设计初衷就是锁定项目构建的 Gradle 版本，所以哪怕你本地装了 8.0.2，项目里只要 wrapper 指向别的版本，构建时还是会去下载对应版本。想强制用本地版本，要么改 distributionUrl，要么把缓存目录准备好，没有第三条捷径。

4. Gradle 8.0.2 适配过程中容易踩的连带坑

4.1 AGP 版本不匹配是最常见的翻车点

把 Gradle 升到 8.0.2 之后，如果项目里还是老版本的 Android Gradle Plugin，尤其是 com.android.tools.build:gradle:4.2.0 这种，构建时大概率直接报错。这不是 Gradle 下载有问题，是版本兼容性。

AGP 和 Gradle 的版本关系是强绑定的，官方有兼容表，我照着重点版本列一下：

AGP 版本	最低 Gradle 版本	最低 JDK
4.2.0	6.7.1	8
7.0	7.0	11
7.4	7.5	11
8.0	8.0	17
8.1	8.0	17
8.2	8.2	17

所以如果你要用 Gradle 8.0.2，AGP 至少得是 8.0。AGP 8.0 和 8.1 都要求 Gradle 8.0，正好能对齐。老项目想升上来，AGP 4.2 不能直接跳到 Gradle 8.0.2，需要先把 AGP 升到 8.x，中间大概率还要处理 Kotlin 插件、依赖库的兼容问题。别嫌麻烦，版本矩阵在这里卡着，跳不过去。

4.2 JDK 17 是硬门槛，不是建议

AGP 8.x 要求构建环境 JDK 17。你可能会想"我本地 Java 8 跑得好好的"，但 AGP 8 在 JDK 8/11 下会直接启动失败，报错信息类似 "Unsupported class file major version 61.0" 或 "AGP requires Java 17"。

Android Studio 自带的 JBR（JetBrains Runtime）大概率是 17，IDE 里构建没问题；但如果你用命令行构建、或者 CI 机器上用的是系统 Java，就要检查 JAVA_HOME 是否指向 JDK 17：

java -version
echo $JAVA_HOME

如果不对，可以临时指定：

export JAVA_HOME=/path/to/jdk-17
export PATH=$JAVA_HOME/bin:$PATH

这一步经常被忽略，很多人卡在 AGP 版本上半天，最后发现只是 JDK 没换，很亏。

4.3 deprecated Gradle features 警告到底要不要管

升级到 Gradle 8.0.2 后，不少项目会看到这条输出：

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

先说结论：这是警告，不是错误，构建能正常完成。它的意思是项目里有某个插件或构建脚本用了 Gradle 8 中已经标记废弃的 API，未来 Gradle 9 会直接删掉这些功能。

想知道是哪里引起的，加参数重新跑一次：

./gradlew build --warning-mode all

输出里会标明具体的废弃警告来源，通常是老版本 AGP、老版本 Kotlin Gradle Plugin、或者某个第三方插件。想严格一点，用 --warning-mode=fail 把警告升级成错误，倒逼自己处理完。处理方式基本都是升级对应插件，没有别的捷径。

4.4 Flutter 项目的特殊报错

Flutter 项目升级到 Gradle 8.0.2 时，经常看到这句：

"You are applying Flutter's main Gradle plugin imperatively using the apply script method, which is deprecated."

原因：android/settings.gradle 还在用老式的 apply 脚本方式引入 Flutter 的 Gradle 插件，而新模板要求用声明式的 plugins DSL。修复方式是在 android/settings.gradle 里改成：

plugins {
    id "dev.flutter.flutter-plugin-loader" version "1.0.0"
    id "com.android.application" version "8.0.0" apply false
    id "com.android.library" version "8.0.0" apply false
    id "org.jetbrains.kotlin.android" version "1.8.0" apply false
}

注意这里的 com.android.application 版本也要按上文兼容表来，从 8.0 起步。改完同步一下，这个警告就没了。很多人一上来只改 Gradle 版本，结果被这个报错拦住，其实问题根本不在 Gradle 本身，而在 Flutter 插件的引入方式。

5. 团队协作：让 gradle-8.0.2-all.zip 只下载一次

5.1 内网统一分发

团队人多，每个人都走外网下载一遍 200MB，既慢又浪费带宽。最省事的做法是在内网放一个静态文件服务，把 gradle-8.0.2-all.zip 放上去，然后把团队所有项目的 distributionUrl 统一指向内网地址。

比如用 Nginx 起一个简单目录：

server {
    listen 8080;
    root /data/gradle;
    autoindex on;
}

然后 wrapper 配置改成：

distributionUrl=http\://gradle.internal.example.com:8080/gradle-8.0.2-all.zip

内网下载速度基本是秒开。要注意的是，如果公司内网服务是 HTTP，而项目里其他地方都是 HTTPS，要确认没有混合内容拦截策略误伤下载请求。另外建议内网服务器上也放一份 .sha256 文件，保持和官方目录结构一致，避免 wrapper 校验时找不到校验文件而行为异常。

5.2 GRADLE_USER_HOME 整体迁移

比单文件分发更狠的方案，是把整个 GRADLE_USER_HOME 目录打包复用。这个目录里不只有 wrapper 下载的 Gradle 发行版，还有项目依赖的缓存（caches/modules-2），是真正的"一次构建，处处复用"。

在 CI 场景下尤其好用：跑一次构建，把 ~/.gradle 打包上传，新的执行机直接解压并设置环境变量 GRADLE_USER_HOME 指向它，能省掉几乎全部依赖下载时间。注意两个细节：一是要确保目录完整，别只拷 wrapper/dists 不拷 caches；二是不同操作系统之间不要直接搬目录，Windows 的路径分隔符和权限模型跟 Linux/macOS 不一样，搬过去容易出现奇怪问题。

如果团队走的是内网 Maven 仓库路线，还可以让 Gradle 直接生成 maven 格式的本地仓库：对 library 模块执行 publishToMavenLocal，会在本机 ~/.m2 下生成 pom 和 aar/jar 文件，再配合私服把这目录同步上去，内网里的其他项目就能直接引用，连依赖下载环节都省了。

5.3 Android Studio 每次新建项目都重新下载的根治

"每次新建项目都要重新下载 Gradle" 这个问题，根源在于新项目模板的 wrapper 指向的 Gradle 版本，和你本机缓存不一致。比如你之前用的是 8.0.2，新模板可能给你生成 8.4 的 wrapper，本地没缓存就只能现场下。

两个处理思路：

一是统一团队的项目模板，把 wrapper 版本固定成同一个，从源头避免版本漂移。二是直接在 Android Studio 的设置里指定本地 Gradle：Settings → Build, Execution, Deployment → Build Tools → Gradle，把 "Use Gradle from" 从 wrapper 模式改为指定本地目录，指向你解压好的 gradle-8.0.2。这样 IDE 调度构建时直接用本地版本，不再走 wrapper 下载流程。但要注意项目所需的 Gradle 版本和你指定的本地版本差距不能太大，否则还是会报兼容性问题。

最后再分享一个我自己的习惯：无论用哪种方式下载，我都会先把 zip 放到一个固定的离线包目录里，标上版本号和校验值。这台机器用完了，下台机器直接拷过去，省得重新走一遍下载流程。gradle-8.0.2-all.zip 这东西，本质上就是个"下过一次就不想下第二次"的文件，把第一次的体验优化好，后面就都是顺的。如果你在换源、离线部署之后还遇到其他怪问题，沿着"wrapper 缓存目录是否完整、distributionUrl 是否匹配、JDK 版本是否达标"这三条线排查，大部分情况都能定位到。

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