Android gradle手动处理

6 阅读3分钟

放入 .gradle/wrapper/dists/gradle-xxx-all/<随机哈希目录>/ 后,不需要手动解压(推荐让 Gradle 自动解压并生成校验标记),但必须清理上次卡死残留的临时文件,否则 Gradle 会判定文件损坏或未完成,从而报错或重新下载。

一、随机哈希目录下的文件结构要求

如果你只放入压缩包,首次运行构建时 Gradle 会自动解压并生成标记文件。一个完全正常、不会触发重新下载的哈希目录(如 2qik7nd48slq1ooc2496ixf4i/)最终包含以下 4 项内容:

  1. gradle-xxx-all.zip:你手动下载的完整压缩包(文件名必须与 gradle-wrapper.properties 中请求的名称完全一致)。

  2. gradle-xxx/(文件夹):解压后的 Gradle 核心程序目录(由 Gradle 自动解压生成)。

  3. gradle-xxx-all.zip.ok(空文件):核心校验标记。Gradle 只有检测到这个 .ok 文件,才会认为该版本的 Gradle 已下载且解压成功,从而跳过网络请求。

  4. gradle-xxx-all.zip.lck(锁文件):进程锁文件,构建期间用于防止并发冲突。

注:如果目录下存在 gradle-xxx-all.zip.part(未下载完的分片文件),必须删除。

二、详细操作步骤(避免报错与重新下载)

  1. 获取正确的随机哈希目录 哈希目录名(如 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 已经自动创建好了对应的哈希文件夹。

  2. 清理残留并放入离线包

    • 打开路径:

      • 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 隐藏目录导致校验失败)。

  3. 如果希望手动解压(备选方案) 若因特殊原因需要手动解压,解压出 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
    
  4. 停止守护进程并重新验证 在 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 哈希目录将不再被使用。