简介Gradle 6.5 完整发行包面向 Java 与 Android 开发者特别适用于需要在 Android Studio 中配置构建环境或深入理解 Gradle 工作机制的人群。相较官方下载通路该压缩包提供了一条更快捷的离线获取方式可显著减少环境搭建中的网络等待。包体约 139MB共 2000 个文件主要类型包括 Java 源码、Groovy 与 Kotlin 脚本、HTML 帮助文档、JAR 运行库以及少量配置文件与图标资源目录结构按标准发行版组织bin 下提供不同平台的启动脚本lib 存放运行时依赖docs 为用户指南src 为可查阅的源代码licences 则汇总了许可信息。Gradle 6.5 在增量构建、依赖解析、Android 插件兼容性、Wrapper 安全升级如 TLS 1.3等方面均有改进开发者可借助文档与源码快速定位配置问题并学习自定义插件开发。资源已有 1062 人学习下载内容完整、结构清晰是离线搭建 Gradle 环境、提升构建效率的实用选择。1. gradle-6.5-all.zip 不只是个离线包先分清 bin 与 all 再动手很多人在 Android Studio 里卡在Gradle: Download gradle-6.5-all.zip这一步时第一反应是去网上找一个离线包下载完却不知道往哪放。这个 zip 是 Gradle 6.5 的完整发行包里面除了运行用的 lib 目录还带了一份源码、文档和官方示例比只求能跑的 bin 版多出不少东西。拿到它之后真正的分叉路口是你想让它当“命令行工具”还是当“wrapper 的本地分发”。前者要解压配置环境变量后者直接把这一个 zip 交给构建脚本去识别。这篇文章就按这两条线把 gradle-6.5-all.zip 从下载到真正生效的过程拆开讲包括解压放哪、Gradle JVM 怎么对齐、AGP 版本怎么匹配以及最常见的五个翻车现场。适合正在搭构建环境、被 Gradle 下载折磨的 Android 和 Java 开发者。2. 从 zip 到命令行可用Gradle 6.5 的安装路径与环境变量2.1 为什么选 all 而不是 bin本地缓存、源码调试与 wrapper 分发Gradle 官网每个版本会同时给出两个 zipgradle-6.5-bin.zip和gradle-6.5-all.zip。很多人顺手点了第一个因为页面默认把 bin 放在下载按钮上。但如果你是在搭离线构建环境我一般会直接选 all。差别不在能不能跑而在你后面会不会多花半小时补东西。对比项gradle-6.5-bin.zipgradle-6.5-all.zip内容bin、lib 等运行文件bin、lib 之外还有 src、docs、samplesIDEA 里查看 Gradle 源码提示 Sources not found直接跳转能看实现给 wrapper 做本地分发能行更常用团队包里基本是 all体积小一些大一些但通常在可接受范围选 all 的第二个实际原因是调试。你自己写 Gradle 插件或者想搞清某个任务的执行逻辑时在 IDEA 里按 Ctrl 点进DefaultTask却提示没有源码这种体验很脱线。src 目录就解决了这个问题。第三个原因才是关键的wrapper 的distributionUrl里如果写的是gradle-6.5-all.zip那你在离线机器上准备的离线包必须也叫这个名字否则 wrapper 不认账。与其下载俩 zip不如一开始就统一成 all。2.2 最小解压安装目录布局与 GRADLE_HOME 配置先把 zip 解压到一个固定的父目录。以 Linux 为例我习惯放在/opt/gradle下因为后面可能还会有 6.5.1、7.x 等多个版本父目录统一切换时只改一个环境变量就行。sudo unzip gradle-6.5-all.zip -d /opt/gradle export GRADLE_HOME/opt/gradle/gradle-6.5 export PATH$GRADLE_HOME/bin:$PATH gradle -v这段命令的逻辑是先解压到/opt/gradle得到/opt/gradle/gradle-6.5这个根目录。GRADLE_HOME必须指向它也就是包含bin、lib的那一层。PATH拼上$GRADLE_HOME/bin是为了让gradle命令直接可用。gradle -v用来验证看到Gradle 6.5和 JVM 信息就说明第一步通了。注意别把GRADLE_HOME设成/opt/gradle。那样会报一个很经典的错误GRADLE_HOME is set to a directory that does not contain a Gradle distribution。只要出现这句话先去看环境变量是不是指少了版本号那一层。Windows 上同理解压到D:\tools\gradle-6.5然后用系统属性里的环境变量配置setx GRADLE_HOME D:\tools\gradle-6.5再把%GRADLE_HOME%\bin加进PATH。setx只对之后新开的终端生效配完记得重开窗口。为了让配置持久化Linux 下要把export写进 shell 配置文件echo export GRADLE_HOME/opt/gradle/gradle-6.5 ~/.bashrc echo export PATH${GRADLE_HOME}/bin:${PATH} ~/.bashrc source ~/.bashrc参数说明~/.bashrc是当前用户的 shell 配置source让它立即生效。如果你用 zsh对应改成~/.zshrc。这套变量只影响当前用户构建机上一般够用。我不太建议用 apt 或 Homebrew 装 Gradle因为包管理器里的版本往往滞后而且构建团队要的是“所有机器同一个版本”手动解压 zip 反而最容易对齐。2.3 命令行跑通第一个构建init 脚本与依赖缓存位置环境变量配好后先在命令行跑一个最小项目确认 Gradle 不只是能打印版本号而是能真正完成构建。cd ~/tmp gradle init --type basic --dsl groovy --project-name demo gradle build --consoleplaingradle init会生成settings.gradle和build.gradle--type basic表示最小骨架--dsl groovy选 Groovy 而不是 Kotlin DSL老项目里 Groovy 仍然最常见。gradle build --consoleplain是第一次构建它会创建~/.gradle目录并把构建产物写进build/。--consoleplain只是让日志更干净不显示彩色进度条排查问题方便。这时要顺手理解两个目录~/.gradle/wrapper/dists放的是 Gradle 分发包~/.gradle/caches放的是依赖 jar 和构建缓存。如果你改了distributionUrl想本地化dists 目录是核心如果你做离线依赖caches 目录是核心。这两个目录都可以通过GRADLE_USER_HOME环境变量整体改位置避免默认放在 C 盘导致空间紧张。第一次构建如果很慢先不要急着骂网络。大型项目里可以把 JVM 参数写进gradle.propertiesorg.gradle.jvmargs-Xmx2048m -XX:MaxMetaspaceSize512m org.gradle.paralleltrue org.gradle.daemontrue参数说明org.gradle.jvmargs是跑构建的守护进程 JVM 内存参数项目大、依赖多时Xmx给足能明显减少卡顿。org.gradle.parallel允许多模块并行构建。org.gradle.daemon让 Gradle 后台长驻避免每次构建都冷启动。很多人以为“打包打半天”是网络问题其实先确认分发包在不在本地缓存、JVM 内存够不够才是正路。3. IDEA 与 Android Studio 接住 6.5wrapper 配置与 Gradle JVM 参数3.1 gradle-wrapper.properties 里的 distributionUrl 指向哪个 zip命令行能跑只是第一步真实项目里你打开别人的代码几乎都是通过 Gradle wrapper 触发构建。wrapper 的逻辑不复杂它读gradle/wrapper/gradle-wrapper.properties按里面的地址找 zip找不到就去下载。这个文件只有几行但决定了离线包到底起不起作用。distributionBaseGRADLE_USER_HOME distributionPathwrapper/dists distributionUrlhttps\://services.gradle.org/distributions/gradle-6.5-all.zip zipStoreBaseGRADLE_USER_HOME zipStorePathwrapper/dists参数说明distributionBaseGRADLE_USER_HOME表示 zip 解压到用户目录下的 Gradle 目录里distributionPathwrapper/dists是具体位置。distributionUrl是你真正要关注的行\:是对冒号的转义不要改成普通冒号否则等号后面的解析可能出问题。末尾的gradle-6.5-all.zip必须和你本地准备的 zip 文件名完全一致。离线环境里最省事的方式是把这一行改成指向本地的file路径distributionUrlfile\:///D:/tools/gradle-6.5-all.zipWindows 本地路径是file:///D:/tools/...三个斜杠Linux 是file:///opt/gradle-6.5-all.zip。把 zip 放在一个团队共享目录里所有人指向同一个地址这就是最简单的分发包管理。3.2 IDEA 里指定 Gradle 6.5Local Distribution 与 Gradle JVMIDEA 里配置 Gradle 有两个入口容易混淆。打开Settings - Build, Execution, Deployment - Build Tools - Gradle第一个要改的是 Gradle 项目里的“Distribution”默认是Wrapper它可以不下载任何本地包每次按distributionUrl现取。第二个要改的是Gradle JVM下拉选择跑构建用的 JDK。如果你已经手动解压了 gradle-6.5-all.zip这里可以选Local installation并指定到解压目录IDEA 就不再去碰网络。但更推荐的做法是保持Wrapper然后把distributionUrl指到本地路径。原因很简单IDEA 自己记录的那份本地安装路径只对当前 IDE 生效而distributionUrl是写在项目仓库里的团队所有人都沿用同一配置。Gradle JVM 和 Project SDK 是两个概念。Project SDK 是编译产物的目标 Java 版本而 Gradle JVM 是实际运行构建守护进程的 JDK。很多人在这翻车Project SDK 选 8Gradle JVM 却选了 JDK 15结果 Gradle 6.5 直接报错Could not determine java version from 15。Gradle 6.5 最高支持到 Java 14所以 Gradle JVM 稳妥选 JDK 8 或 11不要跟着 Project SDK 走也不要跟系统默认 JDK 走。顺手在项目的gradle.properties里补上内存参数因为在 IDEA 里构建时它用的就是这份属性文件org.gradle.jvmargs-Xmx2048m -XX:MaxMetaspaceSize512m org.gradle.paralleltrue org.gradle.cachingtrue参数说明org.gradle.caching是构建缓存开关6.5 里已经稳定开启后二次构建会快不少。注意org.gradle.jvmargs的值如果和 IDEA 里 Gradle JVM 下拉的堆大小设置冲突以gradle.properties为准IDEA 会提示你不用重复设置。3.3 离线环境下的缓存策略从 services.gradle.org 到本地分发网络受限的构建环境里最实用的套路是把分发和依赖分成两步解决。分发包就是 gradle-6.5-all.zip 本身依赖包是项目要下载的 jar。先处理前者因为不解决它整个构建连 Gradle 都起不来。做法是在能联网的机器上下载 gradle-6.5-all.zip放到共享目录或直接拷到目标机器的固定路径比如/opt/gradle/dist/gradle-6.5-all.zip。然后把每个项目的distributionUrl改成这个本地路径。为了让第一次构建不联网跑命令时加--offlinecd /path/to/project ./gradlew assembleDebug --offline注意--offline是告诉 Gradle“不要访问网络”所有依赖都从本地缓存找。如果分发包已经就位但某个依赖不在缓存里它会立刻报缺失清单而不会傻等。这一步能快速区分问题在哪报distributionUrl相关是分发没本地化报某个 jar 缺失是依赖缓存没同步。Android Studio 里构建卡在Running Gradle task assembleDebug的八成就是第一步没做干净。如果不想每次敲--offline也可以在gradle.properties里写org.gradle.offlinetrue效果一样但这个属性是全局的团队里如果有人需要临时联调远程仓库记得改回来。4. Gradle 6.5 的版本兼容表AGP、JDK 与插件三方对齐4.1 Gradle 6.5 官方兼容矩阵JDK 8~14 与 AGP 3.5.4~4.1.0Gradle 6.5 有一个硬边界它的运行 JDK 最低需要 8官方验证过可以支持到 Java 14。超过 14 它不认识这是写死在代码里的解析逻辑不是玄学。汇总一下这组兼容关系方便你贴到项目文档里维度Gradle 6.5 的可用范围运行 Gradle 的 JDK最低 8官方验证到 14编译目标的 Java 版本支持到 14Android Gradle Plugin最低 3.5.4最高 4.1.0Android Studio建议 4.1.x 及对应 AGP这个表里最常被忽略的是最后两行。很多新项目用的 AGP 是 4.2.0它的最低 Gradle 要求写着 6.7.1你拿 6.5 去跑就会在同步阶段直接失败。反过来如果团队里有人用 AGP 4.2.0 配 Gradle 7.x 一切正常想当然地降级到 6.5 也要做好踩坑准备版本匹配从来不是“越新越好”而是“按矩阵对齐”。顺带提一句Java 8 的 zip 包仍然是最常见的搭配因为 Android 工具链和大量旧插件在 JDK 11 下偶尔会有小脾气JDK 8 是最稳的底座。4.2 AGP 与 Gradle 版本不匹配的报错链如果你把 AGP 4.2.0 塞进 Gradle 6.5会在同步时报出这样一段话Minimum supported Gradle version is 6.7.1. Current version is 6.5.这不是警告是硬校验AGP 直接拒绝工作。原因在 AGP 的校验逻辑里它对 Gradle 最低版本的要求是明确写在AndroidGradlePlugin里的不满足就中止。解决的路径有两条。一条是把 AGP 降回 4.1.x对应项目根目录build.gradle里的buildscript部分改成buildscript { repositories { google() mavenCentral() } dependencies { classpath com.android.tools.build:gradle:4.1.0 } }参数说明classpath里指定 AGP 版本号降到 4.1.0 后Gradle 6.5 就能通过校验。google()仓库是 AGP 的发布源mavenCentral()提供其他插件依赖。如果你之前用的是 4.2.0降级后记得在 Android Studio 里 Sync 一次让 IDEA 重新解析。第二条路是升级 Gradle 到 6.7.1 以上但这就偏离了本文标题而且改动面更大。所以我的建议很直接既然团队已经锁定了 gradle-6.5-all.zipAGP 就统一用 4.1.x这是最省事的选择。版本匹配表最好直接贴在团队 Wiki 里省得每次新成员都要查一遍。4.3 新项目用 6.5 的注意点Java 14 与 Flutter 工程如果你是拿 Gradle 6.5 跑新项目有几个点值得提前想清楚。第一编译 Java 代码时build.gradle里的sourceCompatibility和targetCompatibility最高只能写 14写成 15 会直接翻车。如果项目只做 Android老老实实配 1.8 即可没必要追高版本。第二Flutter 项目的 Android 工程也走 Gradle它的android/build.gradle里常见的是apply plugin: com.android.application这种命令式写法。在 Gradle 6.5 上跑没问题但你们团队未来升级 Gradle 8 之类的新版本时会遇到关于“imperatively using the apply”的警告到时候得改成pluginsDSL 的声明式写法。我的建议是既然现在还在 6.5把这一类历史债务顺手记下来但不要急着改避免一次改动破坏现有构建。第三Gradle 6.5 已经支持依赖锁定。如果构建机需要可复现结果可以在build.gradle里启用dependencyLocking { lockAllConfigurations() }然后执行gradle dependencies --write-locks生成锁文件。这功能在 6.5 里是稳定可用的对团队协作价值很大不用等升级。5. 装完就翻车的四个场景gradle-6.5-all.zip 的常见坑与排查5.1 坑一invalid zip archive: could not find EOCD现象解压 gradle-6.5-all.zip 时终端直接报invalid zip archive: could not find EOCD或者 IDEA 导入 zip 失败提示类似的无效压缩包错误。原因EOCD 是 zip 文件末尾的中央目录结束标记Gradle 的压缩包必须完整包含这个标记才能被识别。报这个错基本就是下载中断或文件损坏最常见的是浏览器下载到一半断网或者从共享盘拷贝时没有校验文件大小。解决先删掉本地损坏的 zip重新下载然后在解压之前做一次完整性测试unzip -t gradle-6.5-all.zip | tail -n 5 sha256sum gradle-6.5-all.zipunzip -t会遍历压缩包内所有文件并测试完整性最后一行出现No errors detected in compressed data of gradle-6.5-all.zip才算通过。sha256sum计算出哈希值和官方渠道给的校验值比对一致再放进共享目录。我现在拿到任何 zip 包第一件事就是校验而不是急着解压这个习惯救了我很多次。5.2 坑二GRADLE_HOME 指向 bin 目录导致 command not found现象执行gradle -v报command not found或者 IDEA 配置 Local installation 时提示路径无效。原因有两种情况。一是PATH环境变量没生效终端还在用旧 shell 配置二是GRADLE_HOME指向了错误的层级比如/opt/gradle/gradle-6.5/binGradle 启动脚本会顺着GRADLE_HOME去找它同级的 lib 目录结果找不到就罢工了。解决先用echo $GRADLE_HOME确认环境变量值它必须是指向包含bin和lib的根目录。如果确实指错了重新export一次Windows 上检查路径里是否用了反斜杠Gradle 的脚本对路径分隔符比较敏感。改完之后新开一个终端窗口再试因为export只对当前终端生效IDEA 也要重启才能读到新的环境变量。5.3 坑三Gradle JVM 与 JDK 版本冲突现象IDEA 里构建任务跑了一半报Unsupported class file major version 61或者Could not determine java version from 15。原因Gradle 6.5 支持的最高 JDK 是 14但 IDEA 的 Gradle JVM 下拉框选了 JDK 15 或更高。也可能是系统默认的JAVA_HOME指向了新版本Gradle 在启动守护进程时自动探测到了不支持的 JDK。解决确认项目所有入口统一使用 JDK 8 或 11。具体操作是打开 IDEA 设置把 Gradle JVM 改为 11命令行场景下检查JAVA_HOME确保它指向 JDK 11。这两处都对了再跑gradle -v看输出的 JVM 一行显示的版本和你预期一致就说明守护进程用的是对的 JDK。一个记忆口诀Gradle 6.5 只认到 Java 14JDK 15 之后的新特性再香也跟它无关。5.4 坑四distributionUrl 是 -bin离线包白下了现象明明本地准备好了gradle-6.5-all.zip执行./gradlew时日志仍然显示Downloading https://services.gradle.org/distributions/gradle-6.5-bin.zip网络受限时直接卡死。原因项目里的gradle-wrapper.properties的distributionUrl写的是gradle-6.5-bin.zip与本地 zip 文件名不一致。wrapper 的缓存目录按分发包的文件名来识别-bin和-all是两个独立的缓存入口你准备的 all 包不会被动用。解决把distributionUrl改成与 zip 文件名一致的gradle-6.5-all.zip并且指向本地路径同时清掉旧缓存里残留的 bin 目录以免 wrapper 误判本地已经缓存过。rm -rf ~/.gradle/wrapper/dists/gradle-6.5-bin* ./gradlew --offline --version第一行删除 bin 版本残留第二行用--offline验证 wrapper 是否能从本地缓存启动。注意这条命令只是验证真正构建时还是用./gradlew assembleDebug --offline。如果--offline模式能顺利执行说明分发这块已经彻底本地化。5.5 坑五构建卡在 Running Gradle task assembleDebug 或 Downloading现象Android Studio 里执行构建进度条停在Running Gradle task assembleDebug控制台反复出现Downloading https://services.gradle.org/distributions/...半小时不挪窝。原因分发包和依赖包都还没到位。常见组合是distributionUrl虽然指向了本地但项目首次构建仍然需要联网解析google()等远程仓库里的依赖或者在网络受限的环境里连 Gradle 分发包都没下载成功任务直接挂起。解决把分发包的问题通过本地路径解决把依赖的问题通过镜像或内网仓库解决。具体来说distributionUrl指定本地共享盘build.gradle里的repositories换成团队内可访问的仓库然后再离线构建。这种卡顿很磨人我自己的处理顺序是先--offline看能不能立刻暴露缺失依赖如果离线模式下没有报错说明分发已经顺畅卡顿点可能在 IDE 自身的扫描逻辑。血泪经验总结成一句话Gradle 卡住时先分清是“分发没到位”还是“依赖没到位”前者看distributionUrl后者看repositories别一上来就重启 IDE。6. 验证与进阶用 init 脚本与构建扫描确认 6.5 真的生效装完、改完、不翻车最后一步是验证。先在一个真实项目目录里执行./gradlew --version输出里的Gradle 6.5是分发包版本JVM一行的版本号要和你的预期一致。然后再执行一次实际构建比如./gradlew assembleDebug --offline能在离线模式下跑通说明分发包和依赖包都已本地化。gradle --status可以看后台守护进程状态如果显示PID且运行正常说明 daemon 没有反复重启。进阶技巧是全局 init 脚本。Gradle 会在~/.gradle/init.d/下加载所有.gradle文件这些脚本对所有项目生效。团队里网络受限时我一般会在init.gradle里统一仓库配置allprojects { repositories { maven { url https://maven.aliyun.com/repository/google } maven { url https://maven.aliyun.com/repository/central } } }参数说明allprojects把仓库配置应用到所有项目maven块指定镜像地址。这个文件放到团队共享后每个成员在个人机器上拷贝一份构建时就不再频繁访问远程仓库速度有明显提升。注意这个配置是全局的如果你某个项目需要走公司私服可以在这个脚本里用变量区分网络环境。验证构建提速是否真实生效还可以在 6.5 上执行构建时加--scan生成构建扫描报告查看任务耗时和依赖解析详情。在离线环境下这功能需要额外服务支持没配好会报错不用强求。最后说个我自己的习惯。我现在拿到gradle-6.5-all.zip第一件事是sha256sum校验完整性然后解压到固定目录跑gradle -v确认 JVM 版本最后才让项目 wrapper 指向本地路径。这个顺序帮我少走了很多弯路也让我在团队里能一眼看出别人的构建为什么卡在网络上下不来。工具版本本身不复杂复杂的往往是环境、版本和习惯三者叠加出来的问题。希望帮到你。本文还有配套的精品资源点击获取