简介这是一份 Gradle 8.6 的完整发行包面向 Java、Android 以及其他 JVM 生态的开发者解决构建工具获取和版本升级的痛点。Gradle 8.6 聚焦性能、安全与体验新增自定义加密密钥配置缓存能保护构建缓存中的敏感数据同时改进了构建初始化脚手架帮助快速生成项目结构并升级构建创作 API使插件开发者可以更灵活地控制任务执行与资源管理构建速度也有显著提升。压缩包共 2000 个文件以 1962 个 Java 类库和源码为主体另有 34 个 properties 配置文件用于构建参数3 个 txt 说明和 1 个 pdf 官方文档提供使用参考整体约 210MB便于离线安装或内网分发。已有 1669 人学习下载适合希望升级构建链路的个人开发者与团队。解压即可获得 Gradle CLI、Wrapper 脚本及 API 文档可快速接入现有工程或作为新项目的基础环境值得用作迁移至 Gradle 8.6 的高效方案。1. 为什么整个团队都在等 gradle-8.6-all.zip 这一个文件新电脑上第一次跑gradlew build十有八九卡在 Gradle distribution 下载这一步进度条半天不动最后抛一句could not install gradle distribution from ...。Android Studio 新建项目默认把 wrapper 指向 Gradle 8.6而这个文件将近 200MB从国外官方源拖回来非常折磨人。gradle-8.6-all.zip 其实就是 Gradle 8.6 的完整发行包里面带上源码和文档适合 IDE 跳转和离线排查。早点把这份包通过国内镜像或者内网缓存拉下来整个团队都能少踩几小时无效等待。这篇文章写给被 Gradle 下载折腾过的人无论你是搞 Android、Spring Boot 还是纯 Java 后端凡是项目里躺着gradle-wrapper.properties的都需要知道这个 zip 怎么快速拿到、怎么校验、怎么让构建真正用上它而不是反复下载。2. 先搞清楚 gradle-8.6-all.zip 与 bin 的差别下载前 10 分钟的决策很多人看到官网页面上一排 zip 就懵了gradle-8.6-bin.zip和gradle-8.6-all.zip到底差在哪选错又会怎样。这里花 10 分钟把决策做对能省掉后面一整天的排错时间。2.1 all 和 bin 内容差异不止是体积多几十 MBGradle 官方对每个版本提供两类发行包bin只包含运行 Gradle 所需的二进制、启动脚本和基础库all在bin的基础上额外包含 Gradle 自身的完整源码、HTML/PDF 格式的文档以及示例工程。体积上 all 比 bin 大几十 MB这部分多出来的内容对构建没有直接影响但对开发体验影响很大。如果项目使用 IntelliJ IDEA 或者 Android Studio打开 Gradle 相关面板、想跳转到 Gradle 的源码查看某个 Task 的实现IDE 会直接读取 distribution 目录里的源码文件。用bin包时跳转会失败IDE 会提示没有附加源码还需要手动再配一遍。这就是为什么 Android Studio 的 wrapper 模板默认写的是-all.zip它默认假设你会用到 IDE 的深度集成。另一个实际差别是离线排查问题的场景。当构建报错信息指向 Gradle 内部逻辑时本地有源码就能直接翻而不必去网上按报错关键字碰运气。命令行持续集成环境里两者构建结果完全一致为了省流量用 bin 完全可以但如果你本机做开发我一般直接推荐 all。2.2 下载慢的根因官方源与 wrapper 的下载机制gradle-wrapper.properties里默认的distributionUrl指向services.gradle.org这个域名在国内网络环境下连接稳定性并不理想。Gradle wrapper 的下载逻辑是同步拉取下载期间不打印进度百分比几十 MB 的小文件还勉强能等200MB 级的大文件在网络抖动时很容易卡在中间然后因为连接重置直接失败。失败之后 wrapper 会在~/.gradle/wrapper/dists/gradle-8.6-all/目录下留下.part后缀的临时文件和.lck锁文件。下次再执行gradlew时它不会聪明地断点续传而是尝试重新下载这就形成一种玄学般的“每次都在同一个地方失败”。我见过不少同事反复重试了七八次最后发现是缓存目录里的半截文件在捣乱。镜像源能解决这个问题。国内常用的 Gradle 镜像包括腾讯云镜像和华为云镜像它们会同步 Gradle 官方发行目录路径形式一般是根域名下加/gradle/文件命名与官方完全一致。镜像站的作用是让大文件走国内链路速度快得多而且支持断点续传的下载工具拉取时更稳定。2.3 下载动作用 curl 和 wget 把包稳稳拉下来浏览器直接下载大文件容易中断且没有重试机制命令行工具更适合这种场景。Linux 或 macOS 下推荐用wget它的-c参数支持断点续传中断后重新执行命令会从上次的位置继续。wget -c -t 5 -O gradle-8.6-all.zip \ https://mirrors.cloud.tencent.com/gradle/gradle-8.6-all.zip这条命令里-c负责断点续传-t 5表示下载失败后最多重试 5 次-O指定输出文件名。这里以腾讯云镜像为例华为云镜像的地址结构类似目录列表里同样能找到gradle-8.6-all.zip。如果你所在环境没法访问外部镜像也可以在内网搭一个静态文件服务把 zip 放上去供团队共用这比每个人都从公网拖要省事得多。Windows 环境不需要额外安装工具PowerShell 的Invoke-WebRequest就能完成下载curl.exe -L -o gradle-8.6-all.zip https://mirrors.cloud.tencent.com/gradle/gradle-8.6-all.zip注意这里用curl.exe而不是curlWindows PowerShell 里curl是Invoke-WebRequest的别名两者参数完全不兼容直接用会报错。-L参数让 curl 跟随镜像站的跳转-o指定输出文件。下载完成后先别急着解压下一步先做校验防止镜像源同步不完整导致解压失败。3. 把 gradle-8.6-all.zip 变成可用环境Windows 与 Linux 的完整配置下载回来的 zip 只是原材料解压之后配置好环境变量命令行里才能直接运行gradle命令。这一步同时也是 windows 安装并配置 gradle 最常见出问题的地方大多是环境变量没生效或者PATH配错。3.1 Windows 下配置 GRADLE_HOME 与 PATH两种方式先把 zip 解压到一个固定目录我习惯放在D:\tools\gradle-8.6目录名带上版本号方便以后多个版本共存。解压后确认目录结构根目录下应该能看到bin、lib、docs等文件夹路径不要选到内层。第一种方式用setx命令快速写入用户环境变量setx GRADLE_HOME D:\tools\gradle-8.6 setx PATH %PATH%;D:\tools\gradle-8.6\binsetx会把变量持久写入注册表但有两个明显的坑一是PATH值超过 1024 字符时会被截断环境变量整体被破坏二是setx PATH %PATH%;...会把当前进程里合并后的系统与用户 PATH 全部展开再写回容易产生大量重复条目。如果你机器的 PATH 本身就很长我不建议用这种方式。更稳的是走图形界面右键“此电脑”进入“属性 - 高级系统设置 - 环境变量”在用户变量里新建GRADLE_HOME值是解压路径再编辑Path追加%GRADLE_HOME%\bin。改完环境变量后新开的终端窗口才会生效已经开着的窗口不会读到新值这是“明明配好了却提示找不到 gradle”的第一大原因。3.2 Linux 与 macOS 配置写入 shell 配置文件Linux 下同样先解压到固定目录然后写入当前用户的 shell 配置。以 bash 为例sudo mkdir -p /opt/gradle sudo unzip -d /opt/gradle gradle-8.6-all.zip echo export GRADLE_HOME/opt/gradle/gradle-8.6 ~/.bashrc echo export PATH$GRADLE_HOME/bin:$PATH ~/.bashrc source ~/.bashrc这里把解压目录放在/opt/gradle/gradle-8.6GRADLE_HOME指向这个路径PATH把$GRADLE_HOME/bin放在最前面避免系统里其他旧版本 gradle 抢先被找到。source ~/.bashrc让配置立即生效不用重开终端。macOS 用户如果用的是 zsh把上面的~/.bashrc换成~/.zshrc即可。如果你的机器上装了 Homebrew 的 gradle注意它和手动解压的版本可能冲突命令行的which gradle可以查看当前实际用的是哪个。3.3 验证安装gradle -v 与 gradlew 的版本陷阱配置完成后新开一个终端执行gradle -v正常会输出 Gradle 8.6 的版本信息、JVM 版本和操作系统信息。这里有一个很隐蔽的认知差系统 gradle 版本和项目使用的 gradle 版本是两回事。执行gradlew build时项目根目录的gradle-wrapper.properties说了算如果它指向的 distribution 不在本地缓存wrapper 会自己去下载一份根本不看你系统里装了什么。gradle -v这条命令验证的是全局安装是否正确。想要验证项目用的是哪个版本得执行./gradlew -v它的输出会明确显示项目 wrapper 指向的 Gradle 版本。如果两个命令输出的版本号不一致不用慌这是正常现象wrapper 机制本身就是为了让每个项目锁定自己的构建版本。真正需要处理的是第 4 章要讲的 distributionUrl 指向问题。4. 让项目真正用上这份离线包distributionUrl 与镜像仓库配置全局安装好 gradle 只解决了一半问题因为大多数项目根本不直接调gradle命令而是通过gradlew脚本间接构建。如果 wrapper 的 distributionUrl 不做调整你刚才下载的 gradle-8.6-all.zip 等于白下。这一章把 distributionUrl 配置和依赖库镜像一起处理掉构建速度才能有质的提升。4.1 gradle-wrapper.properties 的三种 distributionUrl 写法每个 Gradle 项目根目录下都有一个gradle/wrapper/gradle-wrapper.properties文件里面的distributionUrl控制 wrapper 去哪里下载 Gradle 发行包。默认指向官方源我们需要把它改成国内镜像或本地文件。第一种写法改成国内镜像地址distributionBaseGRADLE_USER_HOME distributionPathwrapper/dists distributionUrlhttps\://mirrors.cloud.tencent.com/gradle/gradle-8.6-all.zip networkTimeout10000 validateDistributionUrltrue zipStoreBaseGRADLE_USER_HOME zipStorePathwrapper/dists注意distributionUrl里的冒号前面有反斜杠这是 Java properties 文件的转义规则冒号在属性值里会被解析为键值分隔符不转义的话 URL 会被截断。networkTimeout是 Gradle 8.x 支持的下载超时设置单位毫秒默认 10000网络不稳定时可以适当调大。validateDistributionUrl会先发一个 HEAD 请求检查 URL 可达性在内网环境下如果代理拦截 HEAD 请求导致校验失败可以把它设为false。第二种写法直接指向本地已下载的 zipdistributionUrlfile\:/D:/tools/gradle-8.6-all.zipLinux 下的写法是file\:///opt/gradle-8.6-all.zip注意协议后是三个斜杠前两个是协议固有的第三个是文件系统根路径。这种方式下 wrapper 不再发起网络请求直接把本地 zip 解压到缓存目录。适合离线环境或者你已经手动下载好包的情况。之前碰到有人把distributionUrl直接指向解压后的目录这是不生效的wrapper 只认 zip 文件。第三种团队内网共用文件服务distributionUrlhttps\://build.internal.example.com/gradle/gradle-8.6-all.zip把 zip 放到内网静态服务器上所有人的构建都从内网拉取速度和稳定性都远好于各人从公网下载。改完 properties 文件后执行./gradlew --version验证是否能正常解析到指定版本的 distribution。4.2 换掉 Maven 仓库init.gradle 里的阿里云镜像配置distribution 下载问题解决后紧接着暴露的就是依赖下载问题。Gradle 构建时会从repositories里声明的仓库拉取依赖默认的 Maven Central 和 Google 仓库在部分网络环境下同样慢。常见的做法是写一个init.gradle脚本放在~/.gradle/init.d/目录下让所有项目全局生效allprojects { 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 } } }这段脚本用allprojects给每个项目追加阿里云镜像源。public仓库代理了 Maven Central 和 JCentergoogle仓库对应 Google Mavengradle-plugin对应 Gradle Plugin Portal覆盖了 Android 和 Java 项目绝大多数依赖来源。init.d下的脚本对所有项目自动生效不需要每个项目去改 build 文件。要注意的是这个脚本是在项目自身repositories基础上追加仓库而不是替换。如果项目里已经声明了官方仓库查找依赖时依然会先请求官方仓库超时后才走镜像。想要彻底替换可以在项目的settings.gradle里用dependencyResolutionManagement的repositoriesMode设置为FAIL_ON_PROJECT_REPOS强制统一使用settings.gradle里声明的仓库这样官方仓库就不会被请求到。4.3 Android 项目与 AGP 版本匹配别再硬塞 Gradle 8.6Android 项目的 Gradle 版本不能随意升级它和 Android Gradle Plugin简称 AGP版本存在严格的兼容矩阵。Gradle 8.6 官方适配的 AGP 版本大约在 8.4 左右如果你项目里 AGP 还是 7.0.4硬把 Gradle 升到 8.6 基本必挂。社区里常见的问题是“androidstudio build:gradle:7.0.4 下载哪个版本比较合适”——答案是别下载 8.6AGP 7.0.4 对应的 Gradle 版本是 7.x 线。// 项目根目录 build.gradle 或 settings.gradle 中声明 AGP 版本 plugins { id com.android.application version 8.4.0 apply false }如果决定跟随 Gradle 8.6建议 AGP 至少升到 8.4。升级后原有的构建脚本会出现一批兼容性问题比如minSdkVersion这类 DSL 方法在 AGP 8 里已被移除相关内容留到第 5 章细说。FLUTTER 项目同理Gradle 8.6 下 Flutter 模板的apply方式会触发you are applying flutters main gradle plugin imperatively using the apply script的警告需要按照新版模板调整插件引入方式。5. gradle 8.6 安装配置常见问题排查5 个翻车现场与修复命令这一章集中整理我实际遇到的 gradle 8.6 相关报错每一条都是先贴现象再给原因和修复方法。这些坑分布在下载、校验、DSL 兼容、废弃 API 和特殊框架接入五个方向覆盖了升级到 Gradle 8.6 后绝大多数团队会撞上的问题。5.1 could not install gradle distribution from 默认源超时现象执行./gradlew build报could not install gradle distribution from https://services.gradle.org/distributions/gradle-8.6-all.zip终端卡在下载阶段很久后失败。原因官方源在国内网络环境下连接不稳定wrapper 下载失败后会在~/.gradle/wrapper/dists/gradle-8.6-all/目录留下.part临时文件。这些残留文件会让后续重试一直失败因为 wrapper 不会主动清理损坏的下载产物。解决先删掉缓存目录中对应版本的残留文件再把 distributionUrl 改为国内镜像。具体操作是把~/.gradle/wrapper/dists/gradle-8.6-all/整个删掉然后按 4.1 节的写法把 distributionUrl 指向腾讯或华为镜像重新执行./gradlew --version。如果网络环境确实无法访问外网改用file://协议指向本地已下载的 zip。5.2 zip 解压报错镜像源文件不完整现象从镜像站下载的 gradle-8.6-all.zip 在执行gradle命令时提示解压失败或者解压到一半报CRC error、central directory not found。原因镜像站的同步可能存在延迟或文件不完整尤其是 Gradle 发布新版本的前几天。有些镜像会用增量同步文件尚未完全到位时下载拿到的 zip 是坏的。解决下载后先做哈希校验不要直接解压。Gradle 官方在发行目录下提供.sha256文件内容是对应 zip 的 SHA-256 值。Linux 下用sha256sum比对sha256sum gradle-8.6-all.zipWindows 下用certutilcertutil -hashfile gradle-8.6-all.zip SHA256把输出的哈希值和官方.sha256文件里的值对比一致再解压。不一致就删除重新下载。校验通过再解压能避免后面所有莫名其妙的构建失败。5.3 error: gradle dsl method not found: minsdkversion()现象老项目升级到 Gradle 8.6 和 AGP 8.x 后构建直接报error: gradle dsl method not found: minsdkversion()定位到build.gradle里的minSdkVersion 21这一行。原因AGP 8.0 开始移除了旧的 DSL 方法名。minSdkVersion、targetSdkVersion、compileSdkVersion这些带Version后缀的写法是 AGP 7 之前时代的产物AGP 7 里被标记废弃AGP 8 里直接删除。2020 年创建的 Spring Boot 老项目如果同时用了旧版 Gradle 插件也会遇到类似情况。解决把build.gradle里的旧 DSL 全部改成无后缀写法android { namespace com.example.app compileSdk 34 defaultConfig { applicationId com.example.app minSdk 21 targetSdk 34 versionCode 1 versionName 1.0 } }minSdk 21和minSdkVersion 21在语义上完全一致但只有新写法能在 AGP 8.x 下编译通过。顺便检查buildToolsVersionAGP 8 已经不再需要手动指定删除即可。5.4 deprecated gradle features used in this build 警告现象构建日志末尾出现deprecated gradle features were used in this build, making it incompatible with gradle 9.0构建本身能通过但每次都在刷警告。原因项目里某个插件或构建脚本调用了 Gradle 8.6 中已被标记废弃的 API。Gradle 对废弃 API 的兼容策略是“还能用但会警告”并在下个大版本彻底移除。这个警告常见于老版本的第三方插件和自定义 Task。解决先定位具体是哪段代码触发了废弃 API执行构建时加上--warning-mode all./gradlew build --warning-mode all输出会列出每个废弃调用的具体位置通常是某个插件的类名和 Task 名。找到后优先升级插件到兼容 Gradle 8.x 的版本。如果插件已经不再维护可以用--warning-mode none暂时屏蔽警告来保证构建可读性但这是个治标不治本的办法后续升级 Gradle 9 时问题还会爆发。5.5 Flutter 项目 apply 主插件报错现象Flutter 项目在 Gradle 8.6 下构建时输出you are applying flutters main gradle plugin imperatively using the apply script随后构建失败或插件不生效。原因Gradle 8.x 对命令式apply插件的使用方式收紧了限制Flutter 旧模板里用apply from: $flutterRoot/packages/flutter_tools/gradle/app.gradle这种脚本方式引入插件在新的 Gradle 版本下不再被推荐。解决升级 Flutter SDK 到适配 Gradle 8.x 的版本新版模板已经改用pluginManagement加includeBuild的方式在settings.gradle里引入 Flutter 插件。pluginManagement { def flutterSdkPath { def properties new Properties() file(local.properties).withInputStream { properties.load(it) } def flutterSdkPath properties.getProperty(flutter.sdk) assert flutterSdkPath ! null, flutter.sdk not set in local.properties return flutterSdkPath }() includeBuild($flutterSdkPath/packages/flutter_tools/gradle) repositories { google() mavenCentral() gradlePluginPortal() } }这段配置让 Flutter 的 Gradle 插件以复合构建的方式被引入替代了旧的apply from写法。之后在app/build.gradle里也要相应改成plugins { id com.flutter.gradle }这种标准声明方式。6. 验证构建没有走错路哈希校验与日志追踪的进阶动作前面几步做完项目能跑起来了但很多人忽略了一个验证动作确认构建过程中 Gradle distribution 到底是从哪来的以及它用的版本是不是 8.6。Log 里一行Downloading往往藏着问题的答案。先验证 distribution 没有走官方源。清空~/.gradle/wrapper/dists/gradle-8.6-all/缓存然后执行./gradlew --version注意观察输出Downloading https://mirrors.cloud.tencent.com/gradle/gradle-8.6-all.zip如果输出里出现这一行说明 wrapper 正在从镜像下载URL 是你配置的地址就是对的。如果没有任何下载输出直接出结果说明本地缓存或者系统 gradle 被直接使用了。再用./gradlew --version确认版本号是 8.6两个条件都满足wrapper 链路才算真正打通。再验证构建依赖的来源。执行一次带--refresh-dependencies的构建观察输出日志里依赖下载的来源域名./gradlew build --refresh-dependencies --info--info会打印依赖解析的详细信息--refresh-dependencies强制绕过本地缓存重新解析。日志中出现的仓库 URL 如果包含maven.aliyun.com说明 4.2 节的镜像配置生效了。如果依然请求repo.maven.apache.org去检查settings.gradle里是不是有repositoriesMode设置把全局脚本覆盖了。我的习惯是每次下载 gradle-8.6-all.zip 后把 zip 原文件保留在一个固定目录不删除。等哪天某个项目需要降级或换版本直接用file://协议指向本地旧包不用重新下载。这算是一份后悔药尤其是镜像站还没同步新版的时候格外管用。另外hash 校验永远做在解压之前别等构建报错再回头查包的问题。希望这些步骤能帮你把 Gradle 8.6 的下载和配置链路走顺。本文还有配套的精品资源点击获取