简介Gradle 8.6 完整发行包面向 Java、Android 及其他 JVM 语言开发者旨在解决项目构建自动化、依赖管理与多模块工程配置等常见痛点。压缩包共 2000 个文件其中 1962 个 Java 类文件构成核心实现辅以 34 个 properties 配置、3 个 txt 说明和 1 份 PDF 指南整体体积约 209.99MB解压后包含 CLI、Wrapper、库和文档。目前已有 1669 人浏览学习适合正在升级构建工具或需要统一构建环境的个人与团队。该版本强化了自定义加密密钥配置缓存可在共享或外部存储场景下保护敏感信息改进了构建初始化脚手架减少手动配置并保证项目结构一致性扩展了构建创作API使插件开发者能更灵活地处理构建生命周期和任务编排同时伴随的编译、依赖解析与缓存性能优化可明显提升迭代效率。开发者可获得一套安全、高效、可定制的 Gradle 8.6 开箱即用环境解压配置后即可上手。1. 快速下载 gradle-8.6-all.zip先搞清楚你卡在哪一步很多从业者第一次接触 Gradle 离线包是在 Android Studio 构建卡死、Jenkins 流水线报Could not install Gradle distribution或者项目从旧版迁移时突然冒出gradle dsl method not found: minsdkversion()。这些问题的源头往往不是代码逻辑而是 Gradle 发行包本身没下对、版本没选对。gradle-8.6-all.zip 是 Gradle 8.6 的完整发行包包含二进制、源码和文档适合离线环境安装、本地构建和团队统一版本。它能解决的是「下载慢、解压即用、版本不一致」这类基础但致命的构建环境问题适合 Android 开发、SpringBoot 旧项目维护者和所有被 Gradle 发行包折磨过的构建工程师。2. 为什么选 gradle-8.6-all.zipbin.zip 与 all.zip 的差别和版本选型2.1 all.zip 和 bin.zip 差在哪多出来的源码和文档用来干嘛Gradle 官方在 services.gradle.org/distributions 下对同一个版本提供两种打包格式gradle-8.6-bin.zip和gradle-8.6-all.zip。按我自己的使用经验绝大多数人用不到 all.zip 里多出来的东西但当你需要调插件、排查构建脚本或者写自定义 Task 时一切就都不一样了。bin.zip只包含可运行的 Gradle 运行时体积比 all.zip 小差不多一半。如果只是为了让项目能构建bin 版足够。但有一个问题当你打开 Gradle 源码想查某个 API 的行为或者 IDE 需要加载 Gradle 源码来提供更精确的自动补全和跳转时bin 版什么都给不了。all.zip 里额外带了一份完整的 Gradle 源码包和 Groovy/Kotlin 文档Android Studio 和 IntelliJ IDEA 识别到之后能把 Gradle 自己的类和方法也纳入索引。对于经常写构建逻辑、维护插件、或者排查deprecated gradle features were used in this build这类告警的人来说all.zip 的源码能直接告诉你这段废弃逻辑到底在哪里被触发。体积换便利这笔账怎么算取决于你的角色。只跑构建的 CI 机器用 bin 就行本地开发机我建议用 all。还有一点团队内离线分发时all.zip 能覆盖所有人的需求省得有人要源码时再单独传一份。2.2 Gradle 8.6 在 8.x 里的定位从 8.5/8.7/8.13 之间怎么选Gradle 8.6 是 2024 年 2 月发布的版本在 8.x 系列里属于一个相对平稳的中间版本。它之前是 8.5之后是 8.7再往后就是 8.8、8.9 一路到 8.13。很多人问我为什么不用最新版答案很简单你的项目不一定受得了。我碰过一个真实的旧项目构建脚本是从 2020 年的 SpringBoot 项目迁过来的用的还是 Groovy DSL 老写法。直接上 Gradle 8.13一跑就报error: gradle dsl method not found: minsdkversion()——这不是 Gradle 自身的问题而是 Android Gradle Plugin 版本太老和新的 Gradle 之间 API 对不上。但同一个项目换到 8.6再把 AGP 升到对应版本构建就直接过了。选 8.6 而不是 8.7/8.13 的另一个理由是兼容性相对稳定。8.7 开始对 Kotlin DSL 有一些行为调整8.10 之后对旧版 Groovy 脚本的告警更激进。如果你的项目构建脚本存在大量历史遗留写法8.6 是一个能跑通且不会被废弃告警淹没的折中点。如果你是从 Android Studio 里触发的下载还要注意 AGP 和 Gradle 版本的匹配关系——AGP 8.2 对应 Gradle 8.2 到 8.6 都是安全区间AGP 8.3 官方推荐的最低 Gradle 版本就是 8.48.6 完全能兼容。具体匹配表在 Android 开发者官网的 AGP 版本说明里有下载前先花两分钟核对能避免后面一连串的依赖冲突。2.3 下载前的三件事校验和、镜像、目录规划下载 gradle-8.6-all.zip 之前我建议先想清楚三件事不然容易白下。第一件事是校验和。Gradle 官方发布页会给出每个发行包的 SHA-256 校验值services.gradle.org/distributions/gradle-8.6-all.zip.sha256 这个文件就是干这个用的。下载完先校验一下再解压尤其是从非官方渠道下载时。我在公司内网部署离线包时见过同事从不明渠道拉了个 zip解压后一执行gradle --version就报各种奇怪的 ClassNotFoundException最后查出来是压缩包本身被截断了。第二件事是镜像源。直连 Gradle 官方服务器下载 all.zip 的速度经常不尽如人意特别是包里带了源码和文档之后体积接近 200MB。常见做法是走腾讯软件源或者阿里云的镜像站路径和官方保持一致的格式只需要把域名换掉。如果你的内网存在 Maven 私服或者制品仓库也可以直接把 gradle-8.6-all.zip 传上去作为团队统一的下载源。这里多说一句某些 IDE 插件自带的下载逻辑只能识别官方 URL遇到这种情况可以直接手动下载后扔到本地的 Gradle 发行包缓存目录里IDE 会优先复用。第三件事是目录规划。我一般会把 Gradle 安装在一个固定目录下比如 Linux 下的/opt/gradle/gradle-8.6或者 macOS 下的~/gradle/gradle-8.6而不是解压到随便一个下载目录。这样做的原因有两个一是 PATH 环境变量指向稳定路径二是后续升级到 8.7、8.8 时可以直接换目录名不需要动环境变量之外的其他配置。Windows 上同理避免把 Gradle 解压到带空格的路径里比如C:\Program Files\Gradle\gradle-8.6这种路径在个别脚本里会出幺蛾子我吃过这个亏后来一律放D:\dev\gradle-8.6。3. 用国内镜像拉取 gradle-8.6-all.zip三个渠道的最小可复现操作3.1 渠道一腾讯镜像直接拉包解压即用如果只是个人机器上要用 Gradle 8.6最简单的方式是直接镜像下载。腾讯软件源里维护了 Gradle 的完整发行包目录路径格式是https://mirrors.tencent.com/gradle/gradle-8.6-all.zip不需要登录直接 wget 或 curl 就能拉。阿里源也有类似结构哪个快用哪个。下载解压之后配置环境变量即可。# 下载 gradle-8.6-all.zip 到 /tmp 目录-L 表示跟随重定向 curl -L -o /tmp/gradle-8.6-all.zip \ https://mirrors.tencent.com/gradle/gradle-8.6-all.zip # 计算 SHA-256 校验和和官方发布页的比对不一致就删除重下 echo $(curl -sL https://services.gradle.org/distributions/gradle-8.6-all.zip.sha256) /tmp/gradle-8.6-all.zip | sha256sum -c - # 解压到 /opt/gradle/注意解压后会自动生成 gradle-8.6 目录 sudo unzip -q /tmp/gradle-8.6-all.zip -d /opt/gradle/ # 确认可执行文件正常 /opt/gradle/gradle-8.6/bin/gradle --version这个流程里值得关注的是校验那一步。通过管道把官方 SHA-256 文件的内容和本地文件名拼在一起再交给sha256sum -c做校验只有校验结果输出OK才继续。我见过不少人跳过校验直接解压结果在构建时碰到鬼打墙一样的报错最后才发现安装包本身有问题。用国内镜像下载的好处不仅仅是速度快更关键的是比不稳定的直连更不容易出现文件截断。3.2 渠道二本地建一个 Gradle 发行包缓存让构建不再反复下载每次用到 Gradle 都要重新下一遍 zip 是非常浪费时间的做法。Gradle 本身有发行包缓存机制默认位置在~/.gradle/wrapper/dists下。只要第一次通过 wrapper 下载过gradle-8.6-all.zip下次构建会用缓存里的包不再联网。但很多人的痛点是第一次触发下载的时候卡半天。这里教你绕过去手动把 zip 放进缓存目录的正确位置让 wrapper 直接识别。# Gradle wrapper 会按 distributionUrl 的 hash 值来决定缓存目录 # distributionUrl 为 https://services.gradle.org/distributions/gradle-8.6-all.zip 时 DIST_DIR$HOME/.gradle/wrapper/dists/gradle-8.6-all HASH_DIR$(ls $DIST_DIR | head -n 1) # 构造符合 gradle wrapper 预期的目录结构并解压 mkdir -p $DIST_DIR/$HASH_DIR unzip -q /tmp/gradle-8.6-all.zip -d $DIST_DIR/$HASH_DIR # 在解压产物里标记下载完成gradle-wrapper 依赖这个标记文件判断是否已下载 touch $DIST_DIR/$HASH_DIR/gradle-8.6-all.zip.ok这里的HASH_DIR是 Gradle 根据 URL 计算出来的目录名不同版本、不同 URL 对应的 hash 都不同。你不需要手动算先执行一次真实的 wrapper 下载让它把目录结构建出来然后取消这次构建再用 ls 看看多出来的目录名把 zip 放进去解压即可。这个技巧特别适合在公司网络环境下预置好所有开发机的 Gradle 缓存省得每个人第一次构建都卡在下载上。3.3 渠道三离线分发到没有外网的构建机很多公司内部有构建机和测试机是不允许访问外网的这时候 gradle-8.6-all.zip 的离线分发就成了刚需。做法不复杂把 zip 拷贝过去用系统包管理器或直接解压都行关键是后续要让 Gradle 不要尝试上网去拉依赖和插件。# 构建机上是 CentOS/RHEL 系时直接解压到 /opt sudo mkdir -p /opt/gradle sudo unzip -q gradle-8.6-all.zip -d /opt/gradle/ # 配置全局环境变量写到 /etc/profile.d/gradle.sh所有用户都能用 echo export GRADLE_HOME/opt/gradle/gradle-8.6 | sudo tee /etc/profile.d/gradle.sh echo export PATH$PATH:$GRADLE_HOME/bin | sudo tee -a /etc/profile.d/gradle.sh # 让当前 shell 立即生效 source /etc/profile.d/gradle.sh # 验证安装 gradle --version离线机器上真正容易出问题的是依赖下载。Gradle 发行包装好了之后构建项目时如果repositories里写的是mavenCentral()或google()它会尝试访问外网。离线环境的常见做法是构建脚本里把仓库地址改成内网 Maven 私服或者在~/.gradle/init.gradle里写一个全局仓库替换逻辑。这个 init 脚本在下文第 6 章有完整写法这里先记住发行包离线只是第一步依赖仓库的离线才是大头。3.4 装好后的 PATH 与 GRADLE_USER_HOME 环境变量Gradle 装好后PATH和GRADLE_USER_HOME这两个环境变量需要认真对待。GRADLE_USER_HOME默认是~/.gradle它控制着所有缓存、wrapper 发行包、daemon 日志的存放位置。如果你的 C 盘或者系统盘空间紧张把它挪到别的盘是明智的选择。# macOS / Linux 下在 .bashrc 或 .zshrc 里设置 export GRADLE_USER_HOME/data/gradle_home export PATH/opt/gradle/gradle-8.6/bin:$PATH # Windows 下通过系统设置添加用户环境变量 # GRADLE_USER_HOME 设为 D:\gradle_home # PATH 追加 D:\dev\gradle-8.6\bin这里有个细节值得说GRADLE_USER_HOME的迁移要保证目录可写而且不同的项目如果共用同一个GRADLE_USER_HOME它们的 wrapper 发行包也共用缓存。好处是省空间坏处是如果两个项目用的 Gradle 版本差异很大缓存目录会越来越大。我一般会定期清理$GRADLE_USER_HOME/wrapper/dists里不再使用的版本这比清理~/.gradle/caches安全得多因为 wrapper 分布包可以随时重新下载而caches里的依赖如果删错了下一次构建全量拉依赖也很痛苦。4. 把 gradle-8.6 接进项目从 wrapper 到旧项目改造4.1 先统一 wrapperdistributionUrl 指向本地或镜像里的 all.zipGradle Wrapper 是项目级 Gradle 版本锁定的标准方案。你项目里的gradle/wrapper/gradle-wrapper.properties文件决定了这个项目用哪个 Gradle 版本。很多团队只会在本地装一个 Gradle 8.6却忘了改 wrapper 文件结果 CI 和同事的机器还是会按旧地址去下载旧版本。# gradle/wrapper/gradle-wrapper.properties distributionBaseGRADLE_USER_HOME distributionPathwrapper/dists distributionUrlhttps\://services.gradle.org/distributions/gradle-8.6-all.zip networkTimeout10000 validateDistributionUrltrue zipStoreBaseGRADLE_USER_HOME zipStorePathwrapper/dists关键参数是distributionUrl注意 URL 里的冒号必须转义成\:。这里把版本锁到 8.6且使用 all.zip这样团队所有人都在同一套环境中。如果你想走镜像加速下载把域名替换成腾讯或阿里镜像的 Gradle 地址也可以但我更建议保持 wrapper 文件里用官方 URL然后通过预置本地缓存3.2 节的方式来加速这样换网络环境时行为一致。networkTimeout单位是毫秒默认 10000 毫秒。如果公司网络对下载限速严重把这个值调大到 60000 毫秒能避免下载到一半被判定超时。4.2 旧版 SpringBoot 项目升级到 8.6build.gradle 里常见的兼容写法Gradle 8.6 对于构建脚本的兼容性整体算好但如果你维护的是 2020 年前后那种用 Groovy DSL 写的 SpringBoot 项目还是会碰到几处需要手动改的地方。最典型的是build.gradle里的依赖写法。旧项目里的compile和runtime配置在 Gradle 7 时代就被移除了8.6 里直接报错。需要改成implementation和runtimeOnly。还有插件应用方式如果用的是apply plugin: java这种旧语法在 8.6 里虽然还能跑但会打出 deprecation 告警建议改成plugins { id java }块。// 旧写法Gradle 6 时代在 8.6 下直接报错或弃用告警 // apply plugin: java // apply plugin: org.springframework.boot // 8.6 下的标准写法 plugins { id java id org.springframework.boot version 2.7.18 } group com.example version 1.0.0 java { sourceCompatibility JavaVersion.VERSION_1_8 targetCompatibility JavaVersion.VERSION_1_8 } repositories { maven { url https://maven.aliyun.com/repository/public } mavenCentral() } dependencies { implementation org.springframework.boot:spring-boot-starter-web implementation org.springframework.boot:spring-boot-starter-data-jpa runtimeOnly mysql:mysql-connector-java:8.0.33 testImplementation org.springframework.boot:spring-boot-starter-test }这里sourceCompatibility和targetCompatibility在新写法下是放在java {}块里的而不是像旧版直接在顶层写。8.6 默认识别 JDK 8 到 JDK 21 的字节码JDK 17 上跑 JDK 8 目标完全没有问题。如果你项目里用了compileJava的options.encoding也建议在java {}块里配好否则中文注释在某些系统的默认编码下会把编译搞挂。升级脚本时别一把梭先在分支上切到 8.6 跑一遍gradle build按报错一条条改比对照迁移文档猜快得多。4.3 从 Android Studio 构建报错看 8.6 的实际行为差异Android 项目升级 Gradle 到 8.6最常碰到的现象是 Android Studio 里点同步或者直接gradle build时报error: gradle dsl method not found: minsdkversion()或类似的方法找不到。这个报错的本质是 Groovy DSL 在 8.6 里对方法调用的解析更严格了。旧版的android { defaultConfig { minsdkVersion 21 } }这种写法以前能蒙混过关8.6 里解析器会直接不认。// android 模块的 build.gradle 里这种写法在 8.6 下会报方法不存在 // android { // defaultConfig { // minSdkVersion 21 // targetSdkVersion 33 // } // } // 正确写法用等号赋值或加上括号 android { defaultConfig { minSdk 21 targetSdk 33 } }minSdkVersion和minSdk的区别看起来只是名字差一点但在 Gradle 8.6 AGP 8.x 的上下文里前者是老 API后者是新 API。如果你用的是 2020 年的老项目AGP 可能是 3.x/4.x 甚至 2.x那你要做的不是改这一行而是升级 AGP。我建议 Android 项目在动 Gradle 8.6 之前先把 AGP 升到 8.1 以上否则会遇到一连串 DSL 不兼容的问题。AGP 8.x 要求 Gradle 最低 8.08.6 完全满足这一个组合是目前最稳的保守选择。5. Gradle 8.6 装好就跑的避坑清单现象、原因、解决5.1 现象一error: gradle dsl method not found: minsdkversion()现象执行gradle build或 Android Studio 同步时直接报error: gradle dsl method not found: minsdkversion()Gradle 版本是 8.6。原因项目里build.gradle的 android 配置用了minSdkVersion这种旧 DSL 写法而对应的 AGP 版本太老新的 Gradle 语法解析器不认。本质上不是 Gradle 8.6 真的删了这个方法是 AGP 插件没注册这个老方法。解决先升级 AGP 到与 Gradle 8.6 匹配的版本官方推荐组合是 AGP 8.2 以上配 Gradle 8.6。然后把minSdkVersion/targetSdkVersion改写成minSdk/targetSdk。如果项目实在动不了 AGP退回 Gradle 4.10 或者 6.7 是唯一的出路但我不建议——那是用新的崩溃风险换旧的兼容性问题。5.2 现象二Could not install Gradle distribution from gradle-8.13-bin.zip现象构建时报Could not install Gradle distribution from gradle-8.13-bin.zip. Reason: ...下载失败或者校验失败卡在某个百分比不动。原因这里虽然报的是 8.13但原理对所有版本都适用。Gradle 尝试从distributionUrl定义的地址下载发行包网络超时、连接被重置、下载到一半文件损坏都会引发这个报错。常见诱因是公司网络对国外域名限速或者限制还有 wrapper 的networkTimeout设置太小。解决先用第 3 章的镜像渠道手动下载对应的 gradle 发行包再通过 3.2 节的方法把它放进本地的 wrapper 缓存目录里。然后把distributionUrl的域名切换成国内镜像。注意切换镜像后 hash 目录名会变如果之前已经有失败的缓存先删掉~/.gradle/wrapper/dists/gradle-8.13-bin整个目录再重试否则 Gradle 会拿损坏的缓存反复报错。这一步我踩过太多次每次都是清理不彻底导致后面做无用功。5.3 现象三Deprecated Gradle features were used in this build现象构建能跑通但结尾有一大段Deprecated Gradle features were used in this build, making it incompatible with Gradle X.X.的告警中文意思是构建里用了已被弃用的特性。原因构建脚本、插件或者两者叠加使用了 Gradle 8.6 标记为废弃的 API。常见来源包括旧版 AGP、老式maven插件、gradle.properties里被废弃的org.gradle.daemon开关以及脚本里直接用compile配置。解决运行一次gradle build --warning-mode all拿到完整的弃用调用站信息日志里会包含哪个脚本哪一行触发了告警。按图索骥逐个修。如果某个弃用来自第三方插件而你暂时无法升版本可以在gradle.properties里设置org.gradle.warning.modesummary把打印压下去但这只是止血。要注意的是Gradle 8.6 里这种告警不影响构建结果但升级到 9.0 时这些特性可能会被直接删掉所以真正要做的是尽快清理。5.4 现象四You are applying Flutters main Gradle plugin imperatively现象Flutter 项目在 Gradle 8.6 下构建报一串You are applying Flutters main Gradle plugin imperatively using the apply script的警告有时还伴随构建失败。原因Flutter 的 Android 工程结构里android/settings.gradle和android/build.gradle的写法偏老。Flutter 官方已经逐步迁移到新的插件声明式写法但老版本 Flutter 生成的模板仍然是命令式apply和 Gradle 8.6 的推荐用法冲突。构建不一定是失败但警告几乎必然出现。解决打开 Flutter 工程的android/settings.gradle把apply from: $flutterRoot/packages/flutter_tools/gradle/app_plugin_loader.gradle这类命令式加载改成基于com.android.application和org.jetbrains.kotlin.android的插件声明或直接升级 Flutter SDK 到 3.16 以上版本重新生成 android 目录。如果你不想动工程结构可以在gradle.properties里加android.suppressUnsupportedCompileSdk34之类的手段压警告但不是长久之计。核心原则是保持 Flutter SDK、AGP、Gradle 三者版本在同一时代别混搭。5.5 现象五JDK 版本对不上导致 daemon 起不来现象执行gradle命令报Unsupported class file major version或者 daemon 进程直接崩掉。原因Gradle 8.6 要求 JDK 8 到 JDK 21 均可运行但它自己编译生成的 daemon JVM 版本和当前 JAVA_HOME 有关。如果你机器的 JAVA_HOME 指向 JDK 22Gradle 8.6 的 daemon 会尝试在 JVM 22 上跑但 Gradle 8.6 没有为 JDK 22 做过完整适配于是崩。解决确认 JAVA_HOME 指向 JDK 17 或 JDK 21。在命令行里跑java -version和echo $JAVA_HOME看当前环境。如果项目本身是 Android 构建AGP 8.x 推荐 JDK 17。mac 上如果装了多个 JDK用/usr/libexec/java_home -v 17来切换Windows 上直接改系统环境变量即可。改完记得gradle --stop停掉已经启动的错误 daemon否则它还会占用内存并继续用旧 JDK 跑。6. 验证 8.6 是否真的装对了一条命令看四个关键信息安装 Gradle 8.6 后验证不能只看能打出版本号就完事。我见过太多「Gradle 装好了但构建还是怪怪的」的情况。执行下面这组命令能一次拿到环境的关键全貌。# 查看 Gradle 版本与 JVM 信息 gradle --version # 重点看四行Gradle 版本、Kotlin/DSL 版本、JVM 版本、OS 版本 # 例如 # ------------------------------------------------------------ # Gradle 8.6 # ------------------------------------------------------------ # Kotlin: 1.9.20 # Groovy: 3.0.17 # Ant: Apache Ant(TM) version 1.10.13 # JVM: 17.0.9 (Oracle Corporation 17.0.99) # OS: macOS 14.2Gradle 版本行必须精确是8.6。JVM 版本必须落在 8 到 21 区间内Android 项目我建议看到17或21。OS 行能帮你发现当前构建环境是 Apple Silicon 还是 Intel这影响某些原生依赖的下载。如果这里的 JVM 不是你预期的版本说明JAVA_HOME指向有问题去改环境变量再重新开终端。验证通过后下一步是把 Gradle 8.6 的价值放大到团队级别。用 init 脚本把 Maven 中央仓库和 Google 仓库全局替换成国内镜像能让整个团队、所有项目都受益不用每个项目单独改repositories。// ~/.gradle/init.gradle allprojects { repositories { // 阿里云公共仓库覆盖绝大多数 Maven 依赖 maven { url https://maven.aliyun.com/repository/public } // 阿里云 Google 代理仓库解决 Android 构建拉不到 google() 的问题 maven { url https://maven.aliyun.com/repository/google } maven { url https://maven.aliyun.com/repository/gradle-plugin } } buildscript { repositories { maven { url https://maven.aliyun.com/repository/public } maven { url https://maven.aliyun.com/repository/gradle-plugin } } } }这段 init 脚本放在~/.gradle/init.gradle后任何 Gradle 项目构建时都会自动加载。注意maven { url ... }里的地址是阿里源如果你的团队内网有 Nexus 或 Artifactory直接替换成内网地址效果更好。init 脚本的加载顺序先于项目本身的repositories所以项目里原有的mavenCentral()和google()声明会被额外追加而不是覆盖——严格来说这会导致仓库列表里既有国内镜像也有原始仓库但 Gradle 会优先从头到尾按顺序找依赖只要镜像靠前速度和可用性都有保障。我现在的工作习惯是任何新环境装完 Gradle第一件事不是跑项目而是跑gradle --version确认四行关键信息再跑一个空项目gradle init --type java-library验证整个构建链路最后把 init.gradle 放置好。这套流程能杜绝百分之九十的「我明明装了为什么还是报错」问题。希望这些踩坑经验能帮你在 Gradle 8.6 的落地路上少走弯路。本文还有配套的精品资源点击获取