被 Gradle 下载折磨了三年,我写了个脚本一键搞定

事情是这样的。

前两天打开一个老项目，Android Studio 弹出来 Gradle Sync 的进度条，然后就开始转圈。

转了五分钟，还在转。

我瞄了一眼底部状态栏，Downloading gradle-5.4.1-all.zip，速度稳定在 0.3MB/s。

一个 120 多兆的文件，按这速度我得等到天荒地老。

这种事儿吧，说实话我已经经历无数次了。每次建新项目、切分支、或者帮同事排查问题，只要涉及到 Gradle 版本变更，就得重新经历一次这种漫长的等待。

不是哥们，2026 年了，下个构建工具还能这么慢？

很多朋友可能不知道，Gradle 下载慢这事儿，根本原因就一个。它默认从官方源 services.gradle.org 下载，服务器在国外，国内访问速度你懂的。

网上搜「Gradle 下载慢」，铺天盖地都是教你改镜像源的。腾讯云有 Gradle 镜像，阿里云也有，把 gradle-wrapper.properties 里的 distributionUrl 改成镜像地址就行。

但说实话，每次手动改这个，也挺烦的。

而且有时候你改了 distributionUrl，Gradle Wrapper 还是会先去官方源检查一下，或者下载到一半断了又得重来。还有那种情况，你直接把 zip 下下来了，但不知道该放哪个目录，放错了 Gradle 还是会重新下。

我自己就踩过这个坑。下了半天的 zip，放到了一个自以为正确的目录，结果 Gradle 根本不认，又给我重新下了一遍。

那一刻我是真的觉得，这事儿就不能自动化吗？

从下载到放到正确的目录，再到解压，不就是几个步骤的事儿吗。

所以我就写了个脚本。

说真的，一开始我也没想搞多复杂，就想写个下载脚本换个源就行了。但写着写着就停不下来了，最后搞出来一个还算完整的东西。

跟大家聊聊这个脚本干了啥。

第一步，下载。脚本支持三个镜像源，腾讯云、阿里云、还有 Gradle 官方源。运行的时候会问你选哪个，默认是腾讯云，直接回车就行。

你想想看，腾讯云镜像在国内的下载速度，基本能跑满带宽。原来 0.3MB/s 的速度，换了镜像源之后直接干到 10MB/s 以上。

120 兆的文件，不到 30 秒就下完了。

第二步，目录结构。脚本下载的 zip 不是乱放，而是按照 Gradle Wrapper 的标准目录结构来放。

标准的目录结构是 dists\gradle-{版本号}\{哈希}\gradle-{版本号内层}\。这个哈希是 distributionUrl 的 MD5 转 base36 得到的。Android Studio 自动下载时就是这么放的，脚本会按照这个结构一模一样的建目录。

也就是说，你下下来的 zip 放到正确位置之后，Gradle 会直接认，不需要额外配置。

第三步，移动。下完之后脚本会自动把 zip 文件移动到刚刚生成的哈希目录里，默认在 C:\Users\你的用户名\.gradle\wrapper\dists 下面。这个目录就是 Gradle Wrapper 存放下载好的 Gradle 发行版的地方。

这一步解决了我之前踩的那个坑，不用再纠结 zip 该放哪儿了。

第四步，解压。zip 下完之后，脚本会自动在同一个哈希目录里解压，而且解压的时候有进度条，你能实时看到解压到哪了。

这个进度条做的时候还踩了个坑。一开始我用的是 PowerShell 自带的 Expand-Archive，结果这玩意不支持进度显示，解压的时候就像卡死了一样，没有任何反馈。后来改成了用 .NET 的 ZipFile 类手动遍历 zip 里的文件逐个解压，才加上进度条。

第五步，长路径检测。-all 版本里有些文件嵌套很深，解压路径可能超过 Windows 默认的 260 字符限制。脚本在解压前会自动检测系统有没有开启长路径支持，如果没有，会尝试自动开启，开启不了也会提示你以管理员运行，尽可能避免解压到一半失败。

另外，脚本的目标目录和镜像源都可以在运行时交互修改，不用去改脚本文件。启动的时候会显示当前配置，然后问你要不要换镜像源、要不要改目录。你如果想用阿里云的源，或者想把文件放到别的目录，直接选就行。

用法也特别简单。双击运行 download-gradle.bat，然后按提示操作就行。

============================================       Gradle 下载工具 (镜像加速)============================================ 当前配置:   目标目录: C:\Users\yfg10\.gradle\wrapper\dists   镜像源:   https://mirrors.cloud.tencent.com/gradle 镜像源: 1.腾讯云(默认)  2.阿里云  3.官方源  4.自定义选择镜像源 (1-4, 回车保持默认):修改目标目录？(Y/N, 回车保持默认): 版本号示例: 6.5-bin  7.5-all  8.0-bin  8.5-all   -bin: 仅二进制(小)  -all: 含源码文档(大)请输入 Gradle 版本号:

输入版本号，比如 7.5-all，脚本就会自动下载、移动到正确目录、解压、创建 .ok 标记，一气呵成。

整个过程，从输入版本号到全部完成，大概 30 秒到 1 分钟，取决于你的网速。

跟之前等 30 分钟比，这个提升还是挺明显的。

脚本纯 Windows 批处理，不依赖任何额外安装的东西，只要有 PowerShell 就行，Windows 10 以上都自带。不需要装 Python，不需要装 Node，不需要装任何乱七八糟的依赖，双击就能跑。

写这个脚本的过程中我也踩了不少坑，坦率的讲比写脚本本身花的时间还多。

最坑的是 Windows 批处理的编码问题。一开始脚本写完，一运行中文全变成乱码了，各种莫名其妙的报错。后来才发现，Windows CMD 默认用 GBK 编码读取 .bat 文件，而我写的是 UTF-8。

改了编码之后又是一堆转义问题。CMD 的引号转义简直是个灾难，双引号里面嵌双引号，转义符 \ 在不同上下文里含义还不一样。最后我用 PowerShell 的 -EncodedCommand 参数，把整个 PowerShell 脚本 base64 编码后传进去，才算彻底绕开了 CMD 的转义地狱。

还有解压的时候报「目录名称无效」，查了半天才发现是 zip 内部路径用 / 分隔，而 Windows 的路径用 \，两者混在一起 .NET 的 ExtractToFile 就不认了。加了一个 .Replace('/', '\\') 才修好。

另外还踩了哈希目录的坑。刚开始我以为 zip 直接放到 dists 下就行，后来发现 Gradle Wrapper 找的目录名是一个哈希值，跟下载 URL 有关。脚本里面就加上了根据 URL 计算 MD5 转 base36 的逻辑，保证目录结构跟 Android Studio 自动下载的一模一样。

这些坑吧，说实话一开始我也没想到。但踩完之后确实学到了不少 Windows 批处理和 PowerShell 的冷知识，这些东西你不去踩坑是学不到的。

回到最开始那个问题，Gradle 下载慢这事儿，其实解决方案一直都在那里。镜像源是公开的，distributions 目录的路径也是固定的，解压更是系统自带的功能。

缺的不是信息，是一个把这些步骤串起来的工具。

我有时候觉得，很多信息差就是这样。不是说你不知道这个信息，而是你不知道怎么把这些信息组合成一个可执行的流程。一个脚本，说到底就是把一个人的经验固化下来，让其他人不用再重复踩坑。

你不用再去搜「Gradle 下载慢怎么办」，不用去查 distributions 目录在哪，不用去研究 zip 解压后目录名为什么跟文件名不一样。这些我都替你踩过了，固化在脚本里了。

这也算是我的一点小贡献吧。

脚本我已经放出来了，在公众号回复「gradle」就能获取下载链接。

不知道对大家有没有用，但如果你也被 Gradle 下载折磨过，试试看吧。

以上，既然看到这里了，如果觉得不错，随手点个赞、在看、转发三连吧，如果想第一时间收到推送，也可以给我个星标⭐~

谢谢你看我的文章，我们，下次再见。