放入 .gradle/wrapper/dists/gradle-xxx-all/<随机哈希目录>/ 后,不需要手动解压(推荐让 Gradle 自动解压并生成校验标记),但必须清理上次卡死残留的临时文件,否则 Gradle 会判定文件损坏或未完成,从而报错或重新下载。
一、随机哈希目录下的文件结构要求
如果你只放入压缩包,首次运行构建时 Gradle 会自动解压并生成标记文件。一个完全正常、不会触发重新下载的哈希目录(如 2qik7nd48slq1ooc2496ixf4i/)最终包含以下 4 项内容:
-
gradle-xxx-all.zip:你手动下载的完整压缩包(文件名必须与gradle-wrapper.properties中请求的名称完全一致)。 -
gradle-xxx/(文件夹):解压后的 Gradle 核心程序目录(由 Gradle 自动解压生成)。 -
gradle-xxx-all.zip.ok(空文件):核心校验标记。Gradle 只有检测到这个.ok文件,才会认为该版本的 Gradle 已下载且解压成功,从而跳过网络请求。 -
gradle-xxx-all.zip.lck(锁文件):进程锁文件,构建期间用于防止并发冲突。
注:如果目录下存在 gradle-xxx-all.zip.part(未下载完的分片文件),必须删除。
二、详细操作步骤(避免报错与重新下载)
-
获取正确的随机哈希目录 哈希目录名(如
2qik7nd48slq1ooc2496ixf4i)是 Gradle 根据gradle-wrapper.properties中的distributionUrl字符串通过 MD5 算出来的,不能自己随便建:-
先在 VS Code 终端运行一次
flutter run,当控制台卡在Downloading [https://services.gradle.org/distributions/gradle-xxx-all.zip](https://services.gradle.org/distributions/gradle-xxx-all.zip)...时,按Ctrl + C终止。 -
此时 Gradle 已经自动创建好了对应的哈希文件夹。
-
-
清理残留并放入离线包
-
打开路径:
-
macOS / Linux:
~/.gradle/wrapper/dists/gradle-xxx-all/<随机哈希目录>/ -
Windows:
C:\Users<用户名>.gradle\wrapper\dists\gradle-xxx-all<随机哈希目录>
-
-
删除残留:将该哈希目录下原有的
.part文件、.lck文件以及可能解压了一半的文件夹全部删除,确保目录为空。 -
放入压缩包:将手动下载好的
gradle-xxx-all.zip复制到这个空的哈希目录中(不要解压,尤其在 macOS 上,浏览器或系统自带解压工具可能会破坏内部bin/gradle的可执行权限或产生__MACOSX隐藏目录导致校验失败)。
-
-
如果希望手动解压(备选方案) 若因特殊原因需要手动解压,解压出
gradle-xxx文件夹后,必须在同级目录下手动创建一个名为gradle-xxx-all.zip.ok的空文件:Bash
# 在哈希目录下执行(以 gradle-8.10.2-all 为例) unzip gradle-8.10.2-all.zip touch gradle-8.10.2-all.zip.ok -
停止守护进程并重新验证 在 VS Code 终端进入项目的
android目录,清理残留锁并验证:Bash
cd android ./gradlew --stop ./gradlew -v执行
./gradlew -v时,终端会显示Unzipping ...,几秒钟内自动解压并生成.ok文件,随后输出 Gradle 版本号,即代表配置成功。
三、一劳永逸方案:直接配置国内镜像源
如果不想每次升级版本都去手动下载和找哈希目录,可以直接修改 Flutter 项目下的 android/gradle/wrapper/gradle-wrapper.properties 文件,将官方地址替换为腾讯云或阿里云镜像:
Properties
# 原地址:
# distributionUrl=https://services.gradle.org/distributions/gradle-8.10.2-all.zip
# 替换为腾讯云镜像(秒下,无需手动放包):
distributionUrl=https://mirrors.cloud.tencent.com/gradle/gradle-8.10.2-all.zip
注意:修改 distributionUrl 后,由于 URL 字符串改变,Gradle 会计算出一个全新的哈希目录名并从国内镜像高速下载,之前手动放的官方 URL 哈希目录将不再被使用。