企业官网建设流程全解析

简介：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 官网每个版本会同时给出两个 zip：gradle-6.5-bin.zip和gradle-6.5-all.zip。很多人顺手点了第一个，因为页面默认把 bin 放在下载按钮上。但如果你是在搭离线构建环境，我一般会直接选 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 --console=plain

gradle init会生成settings.gradle和build.gradle，--type basic表示最小骨架，--dsl groovy选 Groovy 而不是 Kotlin DSL，老项目里 Groovy 仍然最常见。gradle build --console=plain是第一次构建，它会创建~/.gradle目录，并把构建产物写进build/。--console=plain只是让日志更干净，不显示彩色进度条，排查问题方便。

这时要顺手理解两个目录：~/.gradle/wrapper/dists放的是 Gradle 分发包，~/.gradle/caches放的是依赖 jar 和构建缓存。如果你改了distributionUrl想本地化，dists 目录是核心；如果你做离线依赖，caches 目录是核心。这两个目录都可以通过GRADLE_USER_HOME环境变量整体改位置，避免默认放在 C 盘导致空间紧张。

第一次构建如果很慢，先不要急着骂网络。大型项目里可以把 JVM 参数写进gradle.properties：

org.gradle.jvmargs=-Xmx2048m -XX:MaxMetaspaceSize=512m org.gradle.parallel=true org.gradle.daemon=true

参数说明：org.gradle.jvmargs是跑构建的守护进程 JVM 内存参数，项目大、依赖多时Xmx给足能明显减少卡顿。org.gradle.parallel允许多模块并行构建。org.gradle.daemon让 Gradle 后台长驻，避免每次构建都冷启动。很多人以为“打包打半天”是网络问题，其实先确认分发包在不在本地缓存、JVM 内存够不够，才是正路。

3. IDEA 与 Android Studio 接住 6.5：wrapper 配置与 Gradle JVM 参数

3.1 gradle-wrapper.properties 里的 distributionUrl 指向哪个 zip

命令行能跑只是第一步，真实项目里你打开别人的代码，几乎都是通过 Gradle wrapper 触发构建。wrapper 的逻辑不复杂：它读gradle/wrapper/gradle-wrapper.properties，按里面的地址找 zip，找不到就去下载。这个文件只有几行，但决定了离线包到底起不起作用。

distributionBase=GRADLE_USER_HOME distributionPath=wrapper/dists distributionUrl=https\://services.gradle.org/distributions/gradle-6.5-all.zip zipStoreBase=GRADLE_USER_HOME zipStorePath=wrapper/dists

参数说明：distributionBase=GRADLE_USER_HOME表示 zip 解压到用户目录下的 Gradle 目录里，distributionPath=wrapper/dists是具体位置。distributionUrl是你真正要关注的行，\:是对冒号的转义，不要改成普通冒号，否则等号后面的解析可能出问题。末尾的gradle-6.5-all.zip必须和你本地准备的 zip 文件名完全一致。

离线环境里，最省事的方式是把这一行改成指向本地的file路径：

distributionUrl=file\:///D:/tools/gradle-6.5-all.zip

Windows 本地路径是file:///D:/tools/...，三个斜杠；Linux 是file:///opt/gradle-6.5-all.zip。把 zip 放在一个团队共享目录里，所有人指向同一个地址，这就是最简单的分发包管理。

3.2 IDEA 里指定 Gradle 6.5：Local Distribution 与 Gradle JVM

IDEA 里配置 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 选 8，Gradle 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:MaxMetaspaceSize=512m org.gradle.parallel=true org.gradle.caching=true

参数说明：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改成这个本地路径。为了让第一次构建不联网，跑命令时加--offline：

cd /path/to/project ./gradlew assembleDebug --offline

注意--offline是告诉 Gradle“不要访问网络”，所有依赖都从本地缓存找。如果分发包已经就位，但某个依赖不在缓存里，它会立刻报缺失清单，而不会傻等。这一步能快速区分问题在哪：报distributionUrl相关，是分发没本地化；报某个 jar 缺失，是依赖缓存没同步。Android Studio 里构建卡在Running Gradle task 'assembleDebug'的，八成就是第一步没做干净。

如果不想每次敲--offline，也可以在gradle.properties里写org.gradle.offline=true，效果一样，但这个属性是全局的，团队里如果有人需要临时联调远程仓库，记得改回来。

4. Gradle 6.5 的版本兼容表：AGP、JDK 与插件三方对齐

4.1 Gradle 6.5 官方兼容矩阵：JDK 8~14 与 AGP 3.5.4~4.1.0

Gradle 6.5 有一个硬边界：它的运行 JDK 最低需要 8，官方验证过可以支持到 Java 14。超过 14 它不认识，这是写死在代码里的解析逻辑，不是玄学。汇总一下这组兼容关系，方便你贴到项目文档里：

这个表里最常被忽略的是最后两行。很多新项目用的 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.zip，AGP 就统一用 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.zip

unzip -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/bin，Gradle 启动脚本会顺着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 14，JDK 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 指向本地路径。这个顺序帮我少走了很多弯路，也让我在团队里能一眼看出别人的构建为什么卡在网络上下不来。工具版本本身不复杂，复杂的往往是环境、版本和习惯三者叠加出来的问题。希望帮到你。

本文还有配套的精品资源，点击获取