简介Gradle 8.6 是面向 Java、Android 及 JVM 语言开发者的开源构建自动化工具这份 all 版压缩包适合需要快速获取完整发行版、搭建本地构建环境或研究 Gradle 内部实现的开发者。包内共 2000 个文件以 1962 个 java 源码文件为主辅以 34 个 properties 配置、3 个 txt 说明和 1 个 pdf 文档整体约 209.99MB涵盖 CLI、Wrapper 脚本、核心库与文档等完整内容。该版本重点增强了自定义加密密钥配置缓存允许开发者用自有加密策略保护构建中的敏感信息同时改进了构建初始化脚手架与构建创作 API便于插件更灵活地接入构建生命周期。已有 1670 人学习下载读者可借此快速完成环境部署并深入理解缓存安全、项目初始化与插件扩展等机制。1. gradle-8.6-all.zip 快速下载为什么你下的包总在关键时刻掉链子如果你正在搭建 Android 或 Java 多模块项目大概率绕不开 gradle-8.6-all.zip 这个文件。它出现在 Gradle 官方发行版页面也出现在各种构建脚本的 distributionUrl 里。很多人第一次接触它是因为 wrapper 自动下载卡在百分之几不动或者公司内网根本连不上外网仓库。这个包和 -bin 版本的区别很直接all 包含源码和文档bin 只有运行时。对需要离线构建、需要看 Gradle 内部实现、或者要在隔离环境里复现构建问题的团队来说all 版本是刚需。但它的体积也更大下载链路更容易出问题。这篇笔记不讲空泛概念只讲怎么把这个包快速、稳定地拿到本地怎么配到项目里以及那些让你反复重试的坑到底出在哪。2. 先搞清楚 gradle-8.6-all.zip 里到底装了什么2.1 all 与 bin 的差异不是体积是源码可追溯性很多人以为 all 版本只是多了文档其实关键差异在src目录。bin 版本解压后只有lib、bin和少量元数据而 all 版本额外包含src下的 Groovy 和 Kotlin 源码。这意味着当你的构建脚本报出某个 DSL 方法找不到时可以直接翻源码确认方法签名而不是靠猜。对于需要写自定义 Gradle 插件、或者调试构建逻辑的团队这个差异直接决定排查效率。另一个常被忽略的点是all 版本里的docs目录包含完整的 DSL 参考和 API 文档。在离线环境下这相当于把官方文档站搬到了本地。如果你所在的环境无法稳定访问外部文档all 版本就是唯一的参考来源。从校验角度看all 和 bin 的 SHA-256 校验值完全不同。有些团队在内部镜像里混放了两个版本导致 wrapper 校验失败却找不到原因。记住一个原则distributionUrl 指向 all校验文件也必须对应 all。2.2 为什么 wrapper 下载经常卡住分发链路拆解Gradle wrapper 的下载逻辑并不复杂读取gradle-wrapper.properties里的distributionUrl用 Java 的 URL 连接去拉取然后解压到用户目录下的wrapper/dists文件夹。问题出在三个环节。第一默认的distributionUrl指向的是services.gradle.org的重定向地址。这个地址在不同网络环境下解析结果不同有时会指向一个响应很慢的 CDN 节点。第二wrapper 下载没有断点续传机制一旦连接中断整个 zip 要重新下载。第三解压后的目录结构依赖 zip 内部的路径如果下载不完整解压会报zip END header not found但错误信息不会告诉你文件不完整。理解这三层之后解决思路就清晰了要么换一个稳定的下载源要么手动下载后放到 wrapper 能识别的缓存位置要么直接改 distributionUrl 指向内部镜像。下面会逐一给出可操作的方案。2.3 版本号里的 8.6 意味着什么兼容边界Gradle 8.6 对 Java 版本有明确要求运行 Gradle 本身需要 JDK 8 到 JDK 21但构建 Android 项目时Android Gradle Plugin 的版本必须与 Gradle 版本匹配。比如 AGP 8.3 要求 Gradle 8.4 以上AGP 8.4 要求 Gradle 8.6 以上。如果你在项目里强行把 Gradle 降到 8.6 以下AGP 会直接报错拒绝构建。Kotlin DSL 方面Gradle 8.6 内置的 Kotlin 版本是 1.9.20 左右。如果你的build.gradle.kts里用了更高版本的 Kotlin 特性编译构建脚本时会失败。这个边界在升级 Gradle 时经常被忽略导致构建脚本本身编译不过。还有一个隐藏边界Gradle 8.6 对配置缓存的支持更严格。如果你的项目里还有自定义任务直接访问project对象开启配置缓存后会报错。这不是 8.6 引入的问题但 8.6 默认更倾向于启用配置缓存所以升级后暴露出来的概率更高。3. 手动下载 gradle-8.6-all.zip 的三种可靠路径3.1 用 curl 带重试和限速参数拉取最直接的方式是用命令行工具下载。下面这条命令加了重试、超时和断点续传参数比浏览器直接点更可控。# -L 跟随重定向--retry 5 失败重试5次 # --retry-delay 3 每次重试间隔3秒 # -C - 开启断点续传中断后重新执行同命令即可续传 # --connect-timeout 20 连接超时20秒 curl -L --retry 5 --retry-delay 3 -C - \ --connect-timeout 20 \ -o gradle-8.6-all.zip \ https://services.gradle.org/distributions/gradle-8.6-all.zip逻辑说明-C -是断点续传的关键它会让 curl 检查本地已下载文件的大小然后从断点处继续。如果第一次下载到 60% 断了重新执行同一条命令curl 会从 60% 继续而不是从头开始。--retry处理的是连接层面的临时失败比如 DNS 解析超时或 TLS 握手失败。参数调整建议如果你的网络环境对单连接限速严重可以加--limit-rate 2M限制速率避免触发某些中间设备的流控。但限速会拉长下载时间只在反复断连时使用。下载完成后务必校验文件大小all 版本大约在 200MB 上下如果只有几十 MB说明下错了版本。3.2 校验 SHA-256 再放进 wrapper 缓存目录下载完成后不要急着解压先校验哈希。官方发行版页面会提供 SHA-256 值你也可以用下面命令自己算。# 计算下载文件的 SHA-256 sha256sum gradle-8.6-all.zip # 对比官方公布的值如果不一致说明文件损坏或被篡改 # 官方校验值在发行版页面可查这里不写死具体数值校验通过后把 zip 放到 wrapper 能识别的缓存位置。wrapper 的缓存目录结构是~/.gradle/wrapper/dists/gradle-8.6-all/hash/其中hash是根据 distributionUrl 计算出来的。最省事的做法是先让 wrapper 尝试下载一次等它创建好目录后中断然后把手动下载的 zip 放进那个目录再重新执行构建命令。# 查看 wrapper 缓存目录结构 ls ~/.gradle/wrapper/dists/ # 进入对应版本目录把 zip 放进去 # 注意不要手动解压wrapper 会自己解压 cp gradle-8.6-all.zip ~/.gradle/wrapper/dists/gradle-8.6-all/*/逻辑说明wrapper 在下载前会先创建目标目录然后下载 zip 到该目录最后解压。如果你手动把 zip 放进去wrapper 检测到文件已存在且大小匹配就会跳过下载直接解压。这个技巧在内网环境非常实用相当于用离线包骗过 wrapper 的下载检查。3.3 改 distributionUrl 指向内部镜像的写法如果团队有内部制品库可以把gradle-wrapper.properties里的地址改掉。改之前先确认内部镜像的目录结构和官方一致。# gradle/wrapper/gradle-wrapper.properties # 原始地址 # distributionUrlhttps\://services.gradle.org/distributions/gradle-8.6-all.zip # 改为内部镜像地址注意转义冒号和斜杠 distributionUrlhttps\://internal-repo.example.com/gradle/gradle-8.6-all.zip distributionSha256Sum填入对应的SHA-256值逻辑说明distributionSha256Sum是可选项但强烈建议填上。一旦填了wrapper 下载后会校验哈希不匹配就报错。这能防止内部镜像同步了错误的文件却没人发现。注意 properties 文件里冒号和等号需要转义这是 Java Properties 格式的要求漏掉转义会导致解析失败。参数调整如果内部镜像需要认证distributionUrl 里不能直接写用户名密码正确做法是在~/.gradle/gradle.properties里配置仓库认证信息或者用环境变量注入。把凭据写进 wrapper properties 会随代码提交泄露这是血泪教训。4. 把下载好的包接进项目wrapper 配置与离线构建4.1 修改 gradle-wrapper.properties 的四个关键字段wrapper properties 文件里不止 distributionUrl 一个字段下面四个需要一起看。# 分发地址指向 all 版本 distributionUrlhttps\://services.gradle.org/distributions/gradle-8.6-all.zip # 校验和防止下载损坏 distributionSha256Sum官方SHA-256值 # 解压后的目录名一般不用改 distributionPathwrapper/dists # 是否在下载后保留 zip默认 false调试时可改 true zipStoreBaseGRADLE_USER_HOME zipStorePathwrapper/dists逻辑说明distributionSha256Sum如果留空wrapper 会跳过校验这在快速验证时方便但生产环境不建议。zipStoreBase和zipStorePath决定 zip 存放位置默认放在用户目录下。如果你希望把依赖都收在项目目录内可以改成项目相对路径但要注意别把大文件提交到版本控制。参数调整distributionUrl里的版本号必须和distributionSha256Sum对应。换版本时两个字段要同时改只改一个会导致校验失败。有些团队用脚本自动生成这个文件记得在脚本里把两个值绑定在一起。4.2 离线模式下让 gradle 8.6 正常工作的依赖缓存光有 Gradle 发行版还不够项目依赖的第三方库也需要离线可用。Gradle 的依赖缓存默认在~/.gradle/caches/modules-2/files-2.1/下。离线构建时加--offline参数Gradle 会只从缓存读取不发起网络请求。# 先在线构建一次把依赖拉全 ./gradlew build # 然后断网或加 --offline 验证离线构建 ./gradlew build --offline # 如果报某个依赖找不到说明缓存里没有 # 需要回到在线模式补拉或者手动放入缓存逻辑说明--offline模式下Gradle 不会尝试连接任何仓库。如果缓存里缺少某个依赖构建会直接失败并提示缺少的模块。这个模式适合在 CI 环境里验证缓存完整性也适合在隔离网络中构建。注意动态版本号如1.在离线模式下会解析失败因为 Gradle 需要联网检查最新版本。离线构建要求所有依赖都锁定具体版本这是很多团队在切换离线模式时翻车的地方。4.3 用 init 脚本统一团队内的 Gradle 分发地址如果团队里每个人都要手动改 wrapper properties容易漏改或改错。更稳妥的做法是用 init 脚本统一配置。// ~/.gradle/init.gradle // 统一替换所有项目的 distributionUrl allprojects { buildscript { repositories { maven { url https://internal-repo.example.com/maven } } } } // 更直接的方式在 gradle.properties 里设置 // 但 distributionUrl 不支持全局覆盖只能逐项目改逻辑说明init 脚本可以统一仓库地址但distributionUrl是 wrapper 层面的配置init 脚本管不到。所以团队统一分发地址的正确做法是维护一个 wrapper properties 模板新项目创建时直接复制。或者写一个初始化脚本在项目创建阶段就写入正确的地址。参数调整如果团队用 CI 流水线可以在流水线里加一步检查确认所有项目的distributionUrl都指向内部镜像。这个检查用简单的 grep 就能实现能避免有人不小心提交了默认地址。5. 下载与配置 gradle-8.6-all.zip 的避坑清单5.1 坑一下载到一半断了重试后文件损坏现象wrapper 报zip END header not found或解压到一半失败。原因下载不完整zip 文件尾部缺失。解决不要依赖 wrapper 的重试手动用 curl 的-C -断点续传下载后校验 SHA-256。如果已经损坏删掉重新下不要试图修复。5.2 坑二distributionUrl 改了但校验值没改现象wrapper 报Verification failed: checksum does not match。原因换了下载地址但distributionSha256Sum还是旧值。解决要么同步更新校验值要么暂时清空该字段。清空只是临时手段生产环境必须填对。5.3 坑三all 版本放进缓存目录但 wrapper 不识别现象手动放了 zipwrapper 仍然重新下载。原因缓存目录的 hash 子目录名不对或者 zip 文件名不匹配。解决先让 wrapper 自己下载一次观察它创建的目录名和期望的文件名然后按同样的命名放入。不要自己猜目录结构。5.4 坑四离线构建时动态版本解析失败现象--offline模式下报Could not resolve dynamic version。原因项目里用了1.或latest.release这类动态版本。解决把所有动态版本改成固定版本或者在离线构建前先在线解析一次并锁定。Gradle 的依赖锁定功能可以生成gradle.lockfile锁定后离线构建就能正常解析。5.5 坑五JDK 版本不匹配导致 Gradle 启动失败现象执行./gradlew时报Unsupported class file major version。原因当前 JAVA_HOME 指向的 JDK 版本超出了 Gradle 8.6 的支持范围。解决确认 JDK 版本在 8 到 21 之间。如果系统里有多个 JDK用JAVA_HOME环境变量显式指定或者在gradle.properties里设置org.gradle.java.home指向正确的 JDK 路径。6. 进阶把 gradle-8.6-all.zip 做成可复用的内部基线6.1 用校验和锁定版本避免“昨天还能构建今天就不行”构建环境最怕的是不可复现。今天能构建明天换台机器就不行往往是因为 Gradle 发行版被静默更新了。虽然官方发行版不会改内容但内部镜像如果同步策略有问题可能把不同版本混在一起。解决办法是在 wrapper properties 里写死distributionSha256Sum并且把这个文件纳入版本控制。任何人拉下代码wrapper 都会校验哈希不匹配就报错而不是悄悄用一个错误的版本继续构建。这个习惯看起来麻烦但能省掉大量“为什么他的机器能构建我的不行”的排查时间。我一般会在项目根目录放一个gradle/wrapper/gradle-wrapper.properties并且把distributionSha256Sum作为必填项。CI 流水线里加一步校验确认这个字段不为空。6.2 用本地文件协议做完全离线的分发如果整个团队都在隔离网络中可以把 gradle-8.6-all.zip 放在共享存储上然后用file://协议指向它。# 指向本地文件系统或挂载的网络存储 distributionUrlfile\:/opt/gradle-dists/gradle-8.6-all.zip逻辑说明file://协议下wrapper 直接从本地路径读取 zip不发起任何网络请求。这比内部 HTTP 镜像更可靠因为不依赖网络服务。注意路径要写绝对路径并且确保所有构建节点都挂载了同一个存储。参数调整如果共享存储的路径在不同操作系统上不一样可以用环境变量注入。但 wrapper properties 不支持环境变量替换所以这个方案要求团队内路径统一。如果做不到统一还是用内部 HTTP 镜像更灵活。6.3 验证下载完整性的三个命令最后给三个我每次下载大文件都会用的命令花不了几秒钟但能避免很多返工。# 1. 查看文件大小all 版本大约 200MB 左右 ls -lh gradle-8.6-all.zip # 2. 计算 SHA-256 并对比官方值 sha256sum gradle-8.6-all.zip # 3. 测试 zip 完整性不实际解压 unzip -t gradle-8.6-all.zip | tail -5逻辑说明unzip -t会逐个检查 zip 内的文件条目最后输出No errors detected表示文件完整。这个命令比直接解压快适合在下载后快速验证。如果输出里有bad CRC或incomplete说明文件损坏需要重新下载。这三个命令我一般写成一个小脚本下载后自动执行。看起来是小事但当你赶着出包却卡在解压失败时就会明白这几秒钟的校验有多值。希望帮到你。本文还有配套的精品资源点击获取
简介Gradle 8.6 是面向 Java、Android 及 JVM 语言开发者的开源构建自动化工具这份 all 版压缩包适合需要快速获取完整发行版、搭建本地构建环境或研究 Gradle 内部实现的开发者。包内共 2000 个文件以 1962 个 java 源码文件为主辅以 34 个 properties 配置、3 个 txt 说明和 1 个 pdf 文档整体约 209.99MB涵盖 CLI、Wrapper 脚本、核心库与文档等完整内容。该版本重点增强了自定义加密密钥配置缓存允许开发者用自有加密策略保护构建中的敏感信息同时改进了构建初始化脚手架与构建创作 API便于插件更灵活地接入构建生命周期。已有 1670 人学习下载读者可借此快速完成环境部署并深入理解缓存安全、项目初始化与插件扩展等机制。1. gradle-8.6-all.zip 快速下载为什么你下的包总在关键时刻掉链子如果你正在搭建 Android 或 Java 多模块项目大概率绕不开 gradle-8.6-all.zip 这个文件。它出现在 Gradle 官方发行版页面也出现在各种构建脚本的 distributionUrl 里。很多人第一次接触它是因为 wrapper 自动下载卡在百分之几不动或者公司内网根本连不上外网仓库。这个包和 -bin 版本的区别很直接all 包含源码和文档bin 只有运行时。对需要离线构建、需要看 Gradle 内部实现、或者要在隔离环境里复现构建问题的团队来说all 版本是刚需。但它的体积也更大下载链路更容易出问题。这篇笔记不讲空泛概念只讲怎么把这个包快速、稳定地拿到本地怎么配到项目里以及那些让你反复重试的坑到底出在哪。2. 先搞清楚 gradle-8.6-all.zip 里到底装了什么2.1 all 与 bin 的差异不是体积是源码可追溯性很多人以为 all 版本只是多了文档其实关键差异在src目录。bin 版本解压后只有lib、bin和少量元数据而 all 版本额外包含src下的 Groovy 和 Kotlin 源码。这意味着当你的构建脚本报出某个 DSL 方法找不到时可以直接翻源码确认方法签名而不是靠猜。对于需要写自定义 Gradle 插件、或者调试构建逻辑的团队这个差异直接决定排查效率。另一个常被忽略的点是all 版本里的docs目录包含完整的 DSL 参考和 API 文档。在离线环境下这相当于把官方文档站搬到了本地。如果你所在的环境无法稳定访问外部文档all 版本就是唯一的参考来源。从校验角度看all 和 bin 的 SHA-256 校验值完全不同。有些团队在内部镜像里混放了两个版本导致 wrapper 校验失败却找不到原因。记住一个原则distributionUrl 指向 all校验文件也必须对应 all。2.2 为什么 wrapper 下载经常卡住分发链路拆解Gradle wrapper 的下载逻辑并不复杂读取gradle-wrapper.properties里的distributionUrl用 Java 的 URL 连接去拉取然后解压到用户目录下的wrapper/dists文件夹。问题出在三个环节。第一默认的distributionUrl指向的是services.gradle.org的重定向地址。这个地址在不同网络环境下解析结果不同有时会指向一个响应很慢的 CDN 节点。第二wrapper 下载没有断点续传机制一旦连接中断整个 zip 要重新下载。第三解压后的目录结构依赖 zip 内部的路径如果下载不完整解压会报zip END header not found但错误信息不会告诉你文件不完整。理解这三层之后解决思路就清晰了要么换一个稳定的下载源要么手动下载后放到 wrapper 能识别的缓存位置要么直接改 distributionUrl 指向内部镜像。下面会逐一给出可操作的方案。2.3 版本号里的 8.6 意味着什么兼容边界Gradle 8.6 对 Java 版本有明确要求运行 Gradle 本身需要 JDK 8 到 JDK 21但构建 Android 项目时Android Gradle Plugin 的版本必须与 Gradle 版本匹配。比如 AGP 8.3 要求 Gradle 8.4 以上AGP 8.4 要求 Gradle 8.6 以上。如果你在项目里强行把 Gradle 降到 8.6 以下AGP 会直接报错拒绝构建。Kotlin DSL 方面Gradle 8.6 内置的 Kotlin 版本是 1.9.20 左右。如果你的build.gradle.kts里用了更高版本的 Kotlin 特性编译构建脚本时会失败。这个边界在升级 Gradle 时经常被忽略导致构建脚本本身编译不过。还有一个隐藏边界Gradle 8.6 对配置缓存的支持更严格。如果你的项目里还有自定义任务直接访问project对象开启配置缓存后会报错。这不是 8.6 引入的问题但 8.6 默认更倾向于启用配置缓存所以升级后暴露出来的概率更高。3. 手动下载 gradle-8.6-all.zip 的三种可靠路径3.1 用 curl 带重试和限速参数拉取最直接的方式是用命令行工具下载。下面这条命令加了重试、超时和断点续传参数比浏览器直接点更可控。# -L 跟随重定向--retry 5 失败重试5次 # --retry-delay 3 每次重试间隔3秒 # -C - 开启断点续传中断后重新执行同命令即可续传 # --connect-timeout 20 连接超时20秒 curl -L --retry 5 --retry-delay 3 -C - \ --connect-timeout 20 \ -o gradle-8.6-all.zip \ https://services.gradle.org/distributions/gradle-8.6-all.zip逻辑说明-C -是断点续传的关键它会让 curl 检查本地已下载文件的大小然后从断点处继续。如果第一次下载到 60% 断了重新执行同一条命令curl 会从 60% 继续而不是从头开始。--retry处理的是连接层面的临时失败比如 DNS 解析超时或 TLS 握手失败。参数调整建议如果你的网络环境对单连接限速严重可以加--limit-rate 2M限制速率避免触发某些中间设备的流控。但限速会拉长下载时间只在反复断连时使用。下载完成后务必校验文件大小all 版本大约在 200MB 上下如果只有几十 MB说明下错了版本。3.2 校验 SHA-256 再放进 wrapper 缓存目录下载完成后不要急着解压先校验哈希。官方发行版页面会提供 SHA-256 值你也可以用下面命令自己算。# 计算下载文件的 SHA-256 sha256sum gradle-8.6-all.zip # 对比官方公布的值如果不一致说明文件损坏或被篡改 # 官方校验值在发行版页面可查这里不写死具体数值校验通过后把 zip 放到 wrapper 能识别的缓存位置。wrapper 的缓存目录结构是~/.gradle/wrapper/dists/gradle-8.6-all/hash/其中hash是根据 distributionUrl 计算出来的。最省事的做法是先让 wrapper 尝试下载一次等它创建好目录后中断然后把手动下载的 zip 放进那个目录再重新执行构建命令。# 查看 wrapper 缓存目录结构 ls ~/.gradle/wrapper/dists/ # 进入对应版本目录把 zip 放进去 # 注意不要手动解压wrapper 会自己解压 cp gradle-8.6-all.zip ~/.gradle/wrapper/dists/gradle-8.6-all/*/逻辑说明wrapper 在下载前会先创建目标目录然后下载 zip 到该目录最后解压。如果你手动把 zip 放进去wrapper 检测到文件已存在且大小匹配就会跳过下载直接解压。这个技巧在内网环境非常实用相当于用离线包骗过 wrapper 的下载检查。3.3 改 distributionUrl 指向内部镜像的写法如果团队有内部制品库可以把gradle-wrapper.properties里的地址改掉。改之前先确认内部镜像的目录结构和官方一致。# gradle/wrapper/gradle-wrapper.properties # 原始地址 # distributionUrlhttps\://services.gradle.org/distributions/gradle-8.6-all.zip # 改为内部镜像地址注意转义冒号和斜杠 distributionUrlhttps\://internal-repo.example.com/gradle/gradle-8.6-all.zip distributionSha256Sum填入对应的SHA-256值逻辑说明distributionSha256Sum是可选项但强烈建议填上。一旦填了wrapper 下载后会校验哈希不匹配就报错。这能防止内部镜像同步了错误的文件却没人发现。注意 properties 文件里冒号和等号需要转义这是 Java Properties 格式的要求漏掉转义会导致解析失败。参数调整如果内部镜像需要认证distributionUrl 里不能直接写用户名密码正确做法是在~/.gradle/gradle.properties里配置仓库认证信息或者用环境变量注入。把凭据写进 wrapper properties 会随代码提交泄露这是血泪教训。4. 把下载好的包接进项目wrapper 配置与离线构建4.1 修改 gradle-wrapper.properties 的四个关键字段wrapper properties 文件里不止 distributionUrl 一个字段下面四个需要一起看。# 分发地址指向 all 版本 distributionUrlhttps\://services.gradle.org/distributions/gradle-8.6-all.zip # 校验和防止下载损坏 distributionSha256Sum官方SHA-256值 # 解压后的目录名一般不用改 distributionPathwrapper/dists # 是否在下载后保留 zip默认 false调试时可改 true zipStoreBaseGRADLE_USER_HOME zipStorePathwrapper/dists逻辑说明distributionSha256Sum如果留空wrapper 会跳过校验这在快速验证时方便但生产环境不建议。zipStoreBase和zipStorePath决定 zip 存放位置默认放在用户目录下。如果你希望把依赖都收在项目目录内可以改成项目相对路径但要注意别把大文件提交到版本控制。参数调整distributionUrl里的版本号必须和distributionSha256Sum对应。换版本时两个字段要同时改只改一个会导致校验失败。有些团队用脚本自动生成这个文件记得在脚本里把两个值绑定在一起。4.2 离线模式下让 gradle 8.6 正常工作的依赖缓存光有 Gradle 发行版还不够项目依赖的第三方库也需要离线可用。Gradle 的依赖缓存默认在~/.gradle/caches/modules-2/files-2.1/下。离线构建时加--offline参数Gradle 会只从缓存读取不发起网络请求。# 先在线构建一次把依赖拉全 ./gradlew build # 然后断网或加 --offline 验证离线构建 ./gradlew build --offline # 如果报某个依赖找不到说明缓存里没有 # 需要回到在线模式补拉或者手动放入缓存逻辑说明--offline模式下Gradle 不会尝试连接任何仓库。如果缓存里缺少某个依赖构建会直接失败并提示缺少的模块。这个模式适合在 CI 环境里验证缓存完整性也适合在隔离网络中构建。注意动态版本号如1.在离线模式下会解析失败因为 Gradle 需要联网检查最新版本。离线构建要求所有依赖都锁定具体版本这是很多团队在切换离线模式时翻车的地方。4.3 用 init 脚本统一团队内的 Gradle 分发地址如果团队里每个人都要手动改 wrapper properties容易漏改或改错。更稳妥的做法是用 init 脚本统一配置。// ~/.gradle/init.gradle // 统一替换所有项目的 distributionUrl allprojects { buildscript { repositories { maven { url https://internal-repo.example.com/maven } } } } // 更直接的方式在 gradle.properties 里设置 // 但 distributionUrl 不支持全局覆盖只能逐项目改逻辑说明init 脚本可以统一仓库地址但distributionUrl是 wrapper 层面的配置init 脚本管不到。所以团队统一分发地址的正确做法是维护一个 wrapper properties 模板新项目创建时直接复制。或者写一个初始化脚本在项目创建阶段就写入正确的地址。参数调整如果团队用 CI 流水线可以在流水线里加一步检查确认所有项目的distributionUrl都指向内部镜像。这个检查用简单的 grep 就能实现能避免有人不小心提交了默认地址。5. 下载与配置 gradle-8.6-all.zip 的避坑清单5.1 坑一下载到一半断了重试后文件损坏现象wrapper 报zip END header not found或解压到一半失败。原因下载不完整zip 文件尾部缺失。解决不要依赖 wrapper 的重试手动用 curl 的-C -断点续传下载后校验 SHA-256。如果已经损坏删掉重新下不要试图修复。5.2 坑二distributionUrl 改了但校验值没改现象wrapper 报Verification failed: checksum does not match。原因换了下载地址但distributionSha256Sum还是旧值。解决要么同步更新校验值要么暂时清空该字段。清空只是临时手段生产环境必须填对。5.3 坑三all 版本放进缓存目录但 wrapper 不识别现象手动放了 zipwrapper 仍然重新下载。原因缓存目录的 hash 子目录名不对或者 zip 文件名不匹配。解决先让 wrapper 自己下载一次观察它创建的目录名和期望的文件名然后按同样的命名放入。不要自己猜目录结构。5.4 坑四离线构建时动态版本解析失败现象--offline模式下报Could not resolve dynamic version。原因项目里用了1.或latest.release这类动态版本。解决把所有动态版本改成固定版本或者在离线构建前先在线解析一次并锁定。Gradle 的依赖锁定功能可以生成gradle.lockfile锁定后离线构建就能正常解析。5.5 坑五JDK 版本不匹配导致 Gradle 启动失败现象执行./gradlew时报Unsupported class file major version。原因当前 JAVA_HOME 指向的 JDK 版本超出了 Gradle 8.6 的支持范围。解决确认 JDK 版本在 8 到 21 之间。如果系统里有多个 JDK用JAVA_HOME环境变量显式指定或者在gradle.properties里设置org.gradle.java.home指向正确的 JDK 路径。6. 进阶把 gradle-8.6-all.zip 做成可复用的内部基线6.1 用校验和锁定版本避免“昨天还能构建今天就不行”构建环境最怕的是不可复现。今天能构建明天换台机器就不行往往是因为 Gradle 发行版被静默更新了。虽然官方发行版不会改内容但内部镜像如果同步策略有问题可能把不同版本混在一起。解决办法是在 wrapper properties 里写死distributionSha256Sum并且把这个文件纳入版本控制。任何人拉下代码wrapper 都会校验哈希不匹配就报错而不是悄悄用一个错误的版本继续构建。这个习惯看起来麻烦但能省掉大量“为什么他的机器能构建我的不行”的排查时间。我一般会在项目根目录放一个gradle/wrapper/gradle-wrapper.properties并且把distributionSha256Sum作为必填项。CI 流水线里加一步校验确认这个字段不为空。6.2 用本地文件协议做完全离线的分发如果整个团队都在隔离网络中可以把 gradle-8.6-all.zip 放在共享存储上然后用file://协议指向它。# 指向本地文件系统或挂载的网络存储 distributionUrlfile\:/opt/gradle-dists/gradle-8.6-all.zip逻辑说明file://协议下wrapper 直接从本地路径读取 zip不发起任何网络请求。这比内部 HTTP 镜像更可靠因为不依赖网络服务。注意路径要写绝对路径并且确保所有构建节点都挂载了同一个存储。参数调整如果共享存储的路径在不同操作系统上不一样可以用环境变量注入。但 wrapper properties 不支持环境变量替换所以这个方案要求团队内路径统一。如果做不到统一还是用内部 HTTP 镜像更灵活。6.3 验证下载完整性的三个命令最后给三个我每次下载大文件都会用的命令花不了几秒钟但能避免很多返工。# 1. 查看文件大小all 版本大约 200MB 左右 ls -lh gradle-8.6-all.zip # 2. 计算 SHA-256 并对比官方值 sha256sum gradle-8.6-all.zip # 3. 测试 zip 完整性不实际解压 unzip -t gradle-8.6-all.zip | tail -5逻辑说明unzip -t会逐个检查 zip 内的文件条目最后输出No errors detected表示文件完整。这个命令比直接解压快适合在下载后快速验证。如果输出里有bad CRC或incomplete说明文件损坏需要重新下载。这三个命令我一般写成一个小脚本下载后自动执行。看起来是小事但当你赶着出包却卡在解压失败时就会明白这几秒钟的校验有多值。希望帮到你。本文还有配套的精品资源点击获取
