简介面向安卓开发者与构建自动化使用者gradle-6.7-all.zip 是一份完整发行包内置 Gradle 运行环境及依赖库可离线解压使用有效规避官网下载慢或网络不稳的问题。Gradle 在安卓项目中承担编译、打包、资源处理等核心任务6.7 版本优化了依赖解析与缓存机制能自动从 Maven Central、JCenter 等仓库获取所需库并缓存已下载的依赖与构建结果减少重复请求和编译显著加快重复构建、降低资源消耗。压缩包整体约 139.45 MB免去从远程仓库拉取环境的等待配合 Gradle Wrapper 还能锁定项目所需版本方便团队统一构建环境。资源支持多项目构建与插件体系便于在单一顶层脚本中管理多个子项目既适合学习构建脚本与依赖管理也可用于持续集成中的自动测试与部署。目前已有 1143 人学习适合想系统掌握安卓构建流程、或部署离线构建环境的中高级开发者。 第一次被gradle-6.7-all.zip这个文件名支配是 Android Studio 构建时卡在“Downloading https://services.gradle.org/distributions/gradle-6.7-all.zip”的进度条上等了十分钟还是 0。后来又陆续帮几个同事处理过同类问题发现大家踩的坑高度一致下载龟速、distributionUrl 配错、JVM 版本不兼容、依赖缓存损坏、本地 maven 仓库拉不到包。这篇文章就围绕这份 Gradle 6.7 发行包背后最常见的几个真实痛点展开把从下载、安装、配置到跑通构建的完整链路和排查思路讲透。无论你是 Windows 手动安装还是通过 gradlew wrapper 自动拉取又或者只是想搞明白 IDEA 里的 Gradle JVM 为什么总闹脾气这篇内容都能直接用上。我不会只给结论会尽量把“为什么这么做”一起说清楚。1. gradle-6.7-all.zip 这个发行包怎么选才不给自己挖坑1.1 all 和 bin 不只是体积差异Gradle 官方每个版本会同时提供多个压缩包常见的是-bin.zip和-all.zip。gradle-6.7-all.zip里的 “all” 表示包含二进制文件、源码和文档而-bin只包含可运行的程序本身。从实际使用的角度来说两者跑出来的构建结果完全一致但有一个隐形差别-all包中带源码在 IDE 里查看 Gradle API 或插件源码时可以跳到对应实现这在排查插件问题时非常有用。如果你只是需要让项目正常构建用-bin就够下载体积更小、解压更快。但如果你的工作流里经常要读 Gradle 源码或者需要断点调试自定义 Task/Plugin选-all更省心省去之后单独关联源码包的额外操作。很多人不知道的是gradle-wrapper.properties里的distributionUrl也可以在-bin和-all之间切换并不会影响构建产物只影响 wrapper 下载的包类型。1.2 为什么还有大量项目卡在 6.7Gradle 6.7 是 2020 年 10 月发布的版本到今天已经不算新了但它在存量项目里依然常见核心原因有两个。第一Android Gradle Plugin 4.2 要求的最低 Gradle 版本是 6.7.1很多老项目升级到 AGP 4.x 后就停在这个版本线上没有再动过。第二团队内部多项目共用同一套 Gradle 版本升级牵扯面大除非有明确收益否则没有人愿意承担回归风险。选择 Gradle 版本时不能只看 Gradle 自己的新特性还要看三个约束AGP 版本、Kotlin 插件版本、JDK 版本。比如 Gradle 6.7 运行时的 JVM 支持范围是 Java 8 到 Java 15如果系统装了 Java 17 或更高版本直接跑构建大概率会报“不兼容”或“Unsupported class file major version”。这一点在后面的报错排查里会详细展开。1.3 distributionUrl 填什么决定了你从哪下载gradle-wrapper.properties文件里有这么一行distributionUrlhttps\://services.gradle.org/distributions/gradle-6.7-all.zipservices.gradle.org是官方分发服务器国内网络环境直连经常超时这就是“Could not install Gradle distribution from...”报错的主要原因。实际上这个 URL 可以自由更换为任意可访问的镜像地址甚至可以是本地文件路径并不要求一定指向官方 CDN。我在后面会给出具体的镜像替换方案。2. 下载、解压、连通 IDE环境搭建中容易翻车的几个细节2.1 手动安装的正确姿势和路径建议先明确一个概念gradle-6.7-all.zip解压出来的目录是 Gradle 的安装目录不等同于 Gradle 的用户目录。安装目录是程序本身用户目录默认~/.gradle才是缓存、wrapper 分发版本和本地项目数据所在的位置。不要混淆。手动安装流程很简单但有几个细节处理不好就会翻车解压路径务必使用纯英文不要带空格和中文。Windows 下推荐放在D:\dev\gradle-6.7这类目录不要放 C 盘深处带版本号的嵌套路径避免后续命令行访问踩坑。配置环境变量时GRADLE_HOME指向解压后的根目录注意不是bin目录。然后在Path中追加%GRADLE_HOME%\bin这样命令行才能识别gradle命令。设置完环境变量后新开一个终端窗口执行gradle -v终端不会自动刷新旧窗口的环境变量。如果提示“不是内部或外部命令”多半是 Path 没有追加成功或者当前终端没有重启。确认JAVA_HOME。Gradle 自身是一个 JVM 程序找不到 JAVA_HOME 时会提示JAVA_HOME is not set即使 Gradle 6.7 支持到 Java 15也建议先装一个 JDK 8 或 11 作为构建 JVM兼容性最好。2.2 IDEA 和 Android Studio 里怎么关联IDE 里使用 Gradle 有两条路径一条是让 IDEA 直接使用你手动安装的 Gradle另一条是通过项目里的 wrapper 自动下载。后者更推荐因为 wrapper 能锁定项目级版本团队协作时每个人都用同一个 Gradle。但无论哪条路径都要在 IDEA 的设置面板里说清楚三件事Gradle JVM选择哪个 JDK 来运行 Gradle。这里最容易出问题的是选了高版本 JDK比如 Java 17而项目 AGP 或 Kotlin 版本并不支持。Distribution选择Wrapper还是Local installation。选Wrapper时IDEA 会按gradle-wrapper.properties里的distributionUrl下载选Local installation时则直接使用你本地解压的目录。Gradle user home指定缓存目录默认是~/.gradle。如果你有多个项目共用缓存可以保持默认如果磁盘紧张也可以单独指到其他盘。实际遇到最多的情况是IDEA 中配置没问题但构建一直卡在下载就是因为 wrapper 指向的还是官方地址。这时候光改 IDE 设置没用得改gradle-wrapper.properties。2.3 gradlew.bat build 不下载 Gradle 的问题很多人在命令行执行gradlew.bat build发现它没有按预期下载 Gradle既不报错也不继续或者干脆提示无法连接。常见原因有三个第一gradle/wrapper/gradle-wrapper.properties文件缺失或distributionUrl被写坏。缺少distributionUrl时wrapper 不知道要去哪下载分发版本。第二网络层面连接不上官方分发地址。wrapper 脚本本身不打印详细下载进度在部分网络环境下会长时间无响应表面看起来像“没有开始下载”。第三GRADLE_USER_HOME被改到了一个无写权限的目录wrapper 尝试写入缓存时静默失败。排查方式是打开终端执行echo %GRADLE_USER_HOME%如果输出为空说明用的默认~/.gradle那问题基本可以锁定在下载地址或网络本身。需要特别提醒的是gradlew.bat里的distributionUrl指向的下载地址是精确匹配的一旦 URL 拼错字符比如多写一个斜杠wrapper 不会自动帮你纠正。先把 URL 单独复制到浏览器里访问一次能直接下载 zip再放到 wrapper 配置里。3. 下载龟速和依赖拉不下来一条龙排查链路3.1 先确认卡在哪一环遇到 Gradle 相关下载问题不要急着改配置先判断当前是哪个环节慢现象卡住的位置排查方向构建时进度条长时间停在 Downloading gradle-6.7-all.zipwrapper 下载分发版本distributionUrl 镜像下载分发版本很快但后续解析依赖超时依赖仓库访问maven 仓库镜像首次构建成功第二次构建报缓存相关错误Gradle 缓存清理 ~/.gradle/caches日志提示 socket timeout网络层更换镜像或配置代理这个表格基本覆盖了大多数“Gradle 慢”的问题场景。很多教程一上来就让你换镜像没有先定位问题其实是低效的。3.2 wrapper distribution 镜像替换Gradle 发行包的国内镜像目前比较稳定的是腾讯云和华为云。以gradle-6.7-all.zip为例腾讯镜像地址为https://mirrors.cloud.tencent.com/gradle/gradle-6.7-all.zip把gradle-wrapper.properties中的distributionUrl改成上面这个地址保存后重新构建。注意 URL 中的https后面的冒号在 properties 文件里需要用反斜杠转义distributionUrlhttps\://mirrors.cloud.tencent.com/gradle/gradle-6.7-all.zip如果项目是手动下载安装不需要 wrapper那直接去镜像站下载 zip 即可。手动下载的好处是可以用下载工具断点续传速度快、失败可重试比让 wrapper 裸下载稳定得多。还有一个冷门但有效的做法把distributionUrl指向本地文件地址。比如你已经手动下载好了gradle-6.7-all.zip放在D:\downloads\下可以这样写distributionUrlfile\:///D:/downloads/gradle-6.7-all.zip这样 wrapper 会直接从本地 zip 解压完全绕开网络。适合网络环境极差或者完全内网的机器。3.3 依赖仓库镜像与本地 maven 仓库分发版本下载完只是第一步真正耗时的往往是依赖解析。项目根目录的build.gradle或settings.gradle里仓库配置默认是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://maven.aliyun.com/repository/central } }放在settings.gradle的pluginManagement和dependencyResolutionManagement里各写一份插件和依赖就都能走镜像。如果你需要拉取本地 maven 仓库的包比如团队内私服或者本地~/.m2仓库可以加入mavenLocal()repositories { mavenLocal() maven { url https://maven.aliyun.com/repository/public } }这里有一个常见的误区把mavenLocal()放在远程仓库后面会导致本地存在的包也优先去远程拉取拉不到或版本不一致时才会回落到本地。如果你想强制使用本地仓库的特定版本要么把mavenLocal()放在最前面要么干脆去掉远程仓库。这个顺序问题很多人栽过跟头。3.4 如何判定镜像是否生效配置完镜像后怎么确认它真的生效了在gradle-wrapper.properties中检查 distributionUrl构建时观察日志里的下载地址是否变成了镜像域名还可以在本地用户目录执行gradle build --info日志中会打印每个依赖实际从哪个仓库解析出来的路径。如果改完镜像依然很慢用gradle build --refresh-dependencies试试强制刷新依赖缓存有时旧的半成品缓存会让 Gradle 误判依赖状态反复请求已损坏的本地文件。这个命令在首次换镜像后尤其有用。4. 构建报错的最后一公里JVM 版本不兼容与依赖缓存损坏修复实录4.1 核心问题Gradle JVM 到底该选哪个热搜词里有一条很典型“the projects gradle version 6.7.1 is incompatible with the gradle jvm version”。这个报错很多人第一次见都会懵特别是刚把项目从旧机器同步到新机器时。实际上这句话的意思是项目脚本里指定的 Gradle 版本6.7.1与当前运行 Gradle 的 JVM 版本不匹配。Gradle 6.7 的构建运行环境支持 Java 8 到 Java 15超过这个范围的 JVM 在解析 Groovy/Kotlin 脚本或加载 AGP 时会出现类文件版本错误。在 IDEA 中的修复步骤File - Settings - Build, Execution, Deployment - Build Tools - Gradle - Gradle JVM选择一个 JDK 8 或 JDK 11注意不要选最新的 JDK 17/21如果列表里没有可用的 JDK 8/11点击Add JDK手动指定本地安装路径同步项目重新构建命令行场景下通过环境变量来控制运行 JVMset JAVA_HOMEC:\Program Files\Java\jdk-11.0.20 set GRADLE_HOMED:\dev\gradle-6.7 %GRADLE_HOME%\bin\gradle build关键思路是Gradle 版本决定它支持哪些 JVM 版本AGP 和 Kotlin 插件版本又决定了它们能跑在哪些 Gradle 版本上而系统 JVM 则是这一切的运行时底座三者必须同时兼容。碰到诡异的构建报错先检查这个三角关系往往能少走很多弯路。4.2 依赖缓存损坏的识别与修复另一个高频问题Gradles dependency cache may be corrupt (this sometimes occurs after a network connection timeout.)。发生场景通常是网络不稳定时构建中断依赖下载了一半本地缓存里留下残缺文件。后续构建以为这个依赖已经存在尝试读取时发现内容不完整就报出缓存损坏。排查和修复链路按顺序尝试先执行带刷新的构建命令让 Gradle 重新解析依赖gradle build --refresh-dependencies这个命令会让 Gradle 忽略已缓存的动态版本和快照版本重新检查远程仓库。但注意它并不会清空缓存中的损坏文件只会在校验不一致时尝试覆盖。上面的命令没效果删除对应模块的缓存目录。Gradle 6.7 的依赖缓存位于~/.gradle/caches/modules-2/files-2.1可以按报错信息里提示的 group/artifact 路径删除对应文件夹。如果损坏范围较大直接删除整个~/.gradle/caches目录。这是最粗暴也最有效的方式。删除后首次构建会重新下载所有依赖耗时较长所以在网络环境差的场景下务必先把镜像源配置好再删缓存。我自己处理过一个项目删掉 caches 后构建仍报同一个错最后发现是 Windows 上文件被 IDE 进程锁住删除操作根本没生效。所以删除缓存目录后要确认目录真的不存在了或者先关闭 IDE 再删这个细节容易被忽略。5. 让 Gradle 6.7 跑得更顺手的几个配置项5.1 gradle.properties 优化项目根目录的gradle.properties里可以写一些提升构建体验的参数。以 Gradle 6.7 为参考我一般这样配org.gradle.jvmargs-Xmx2048m -XX:MaxMetaspaceSize512m -XX:HeapDumpOnOutOfMemoryError org.gradle.daemontrue org.gradle.paralleltrue org.gradle.workers.max4 org.gradle.cachingtrueorg.gradle.daemontrue让 Gradle 在后台常驻一个守护进程避免每次构建都重新启动 JVM这是感知最明显的提速项。org.gradle.paralleltrue对多模块项目有效单模块项目作用不大。org.gradle.cachingtrue开启构建缓存相同的任务输出在多个项目间可以复用。这里要特别提醒不要随意开启 Gradle 6.7 的 configuration cacheorg.gradle.configuration-cachetrue。这个特性在 6.6 刚引入6.7 版本还不稳定很多第三方插件没有适配开启后反而会出现各种诡异问题。等项目的 Gradle 升到 7.4 以上再考虑会比较稳妥。5.2 离线模式与增量构建如果项目的依赖已经在本地缓存里齐全可以尝试离线构建gradle build --offline离线模式下 Gradle 不会访问任何远程仓库构建时间大幅缩短。但要注意如果某个依赖从未被下载过离线构建会直接报错提示找不到依赖。所以离线模式适合网络不稳定时应急使用不适合日常开发。还有一种组合用法gradle build --offline --build-cache配合本地缓存和构建缓存在依赖未变动的情况下二次构建速度可以快到“秒级”。但前提是你得先维护好本地缓存否则第一次还是会失败。5.3 一个实际的本地仓库接入示例针对“gradle 拉取本地 maven 仓库包”这个需求给一个完整的可参考配置。假设你的libs目录下有一个本地 jar 包my-utils-1.0.jar不想发布到远程仓库也不想手动 install 到本地 maven直接用 flatDir 仓库即可repositories { flatDir { dirs libs } } dependencies { implementation name: my-utils, version: 1.0 }注意 flatDir 仓库的坐标匹配规则和 maven 仓库不同name直接对应 jar 文件名去掉了版本号的部分version对应版本号。如果 jar 文件名是my-utils-1.0.jar上面的写法就匹配上了。如果你希望依赖从~/.m2本地仓库获取用mavenLocal()更合适repositories { mavenLocal() } dependencies { implementation com.example:my-utils:1.0 }前提是这个包已经通过mvn install安装到了本地~/.m2仓库。两种方式的应用场景不同flatDir 适合临时引入原始 jarmavenLocal 适合团队私服依赖链完整、本地做验证的情况。6. 我在实际使用中积累的几个习惯最后分享几个我个人在 Gradle 6.7 使用中的小习惯不一定适合所有人但能帮你减少一些无意义的折腾。第一个习惯是新接手项目先看gradle-wrapper.properties确认 distributionUrl 指向哪里。如果指向官方地址构建大概率会慢先手动下载 zip 或者更换镜像再开始后面的操作。这一步 30 秒钟的检查能省下不少等待时间。第二个习惯是不要试图让一个项目同时适配多个 Gradle 版本。Gradle 的 wrapper 机制存在是有道理的团队内统一版本、统一镜像源、统一构建 JDK才是解决构建环境问题的正道。不同机器上的差异往往是问题排查时最大的干扰源。第三个习惯是Windows 上如果经常遇到 Gradle 下载失败用下载工具先把 zip 拉下来然后通过本地file://路径让 wrapper 使用。这个方法虽然看起来不那么“优雅”但在实际项目中帮我解决过不少网络环境极差的情况。Gradle 6.7 本身不是最新的版本但在工程化落地的角度它依然是很多存量项目的稳定基石。搞清楚它背后的分发、配置、缓存和 JVM 机制无论以后升级到哪个版本这些底层思路都能直接复用。本文还有配套的精品资源点击获取