简介Gradle 8.0.2 是 Gradle 8.0 的第二个补丁版本面向使用 Gradle 构建 Java、Scala、Kotlin 项目的开发者尤其适合需要修复 8.0 系列已知问题的团队。该版本集中修复了元空间耗尽、无显式工具链的 Java/Scala 构建失败、自定义编译器支持被静默放弃、InstrumentingTransformer 生成类文件不一致导致远程构建缓存未命中、已解析配置扩展失效、配置缓存状态更新、插件管理规范状态显示异常、Scala 插件与工具链集成文档缺失、字符串 isBlank 报错等十余项问题并补充了相关文档说明。压缩包共 11587 个文件以 java 源码、html 文档、kt 脚本、jar 包为主另含 png 图示、js/css 样式及少量 groovy、zip、pdf 等整体约 159.92MB目录结构完整便于查阅源码与离线文档。已有 742 人学习下载适合需要稳定构建环境或排查 8.0 升级问题的开发者参考。1. 一个 200MB 的压缩包卡住了整条构建链上周帮同事配环境Android 工程一跑./gradlew assembleDebug就卡在Downloading https://services.gradle.org/distributions/gradle-8.0.2-all.zip进度条半小时不动。这不是网络玄学是 Gradle Wrapper 默认从官方分发地址拉整包而-all版本比-bin多出源码和文档体积接近 200MB弱网环境下失败率极高。gradle-8.0.2-all.zip就是官方发布的完整发行包解压即用包含bin、docs、src和lib适合需要离线构建、想看 Gradle 内部实现、或者被 Wrapper 下载反复折磨的开发者。这篇笔记按「包是什么 → 怎么装 → 怎么让 Wrapper 认它 → 坑在哪」走一遍新手能照着复现熟手能直接抄参数。2. 拆开 gradle-8.0.2-all.zip目录结构与版本选型2.1 all 和 bin 到底差在哪很多人下载时随手点第一个链接结果拿到的是-bin后面想看源码发现src目录不存在。先把两个发行版的差异摆清楚选型就不会反复。对比项gradle-8.0.2-bin.zipgradle-8.0.2-all.zip体积约 100MB约 200MB包含bin/启动脚本是是包含lib/依赖 jar是是包含docs/离线文档否是包含src/源码否是适用场景CI 缓存、纯构建本地开发、源码调试、离线查阅-all多出来的src是 Gradle 自身用 Groovy/Kotlin 写的源码排查插件行为、读DefaultTask实现时直接翻本地文件比在线搜快得多。CI 环境如果只跑构建-bin更省缓存空间但本地开发机我一般直接上-all省得后面为了看一段源码再下一次。2.2 解压后的目录长什么样拿到 zip 后先别急着配环境变量解压看一眼结构后面配GRADLE_HOME才不会指错层级。# 解压到统一目录注意解压后会自动生成 gradle-8.0.2 这一层 unzip gradle-8.0.2-all.zip -d /opt/gradle # 确认目录层级GRADLE_HOME 应指向 gradle-8.0.2而不是 /opt/gradle ls /opt/gradle/gradle-8.0.2 # 预期输出bin docs init.d lib LICENSE NOTICE README这里有个高频翻车点unzip -d /opt/gradle之后实际路径是/opt/gradle/gradle-8.0.2如果环境变量写成/opt/gradle执行gradle -v会报Could not find or load main class org.gradle.launcher.GradleMain。逻辑说明GRADLE_HOME必须精确指向含bin/的那一层bin/gradle脚本内部会基于自身位置反推lib层级错一位就找不到主类。参数上-d指定的是父目录不是最终目录这一点和tar -C的行为一致但很多人按tar的直觉写错。2.3 版本号里的 8.0.2 意味着什么Gradle 版本号是主版本.次版本.补丁8.0.2 属于 8.0 系列的补丁版修的是 8.0.0/8.0.1 的回归问题API 层面与 8.0 兼容。选它而不是 8.1 的常见理由是工程里 AGPAndroid Gradle Plugin版本锁死了兼容区间AGP 8.0 要求 Gradle 8.0 及以上但部分老插件在 8.1 的配置缓存上有行为变化。所以「补丁版 匹配 AGP」是稳妥组合不要盲目追最新。判断方法很简单看工程根目录gradle/wrapper/gradle-wrapper.properties里的distributionUrl它写的就是这个工程期望的版本下载对应包即可别自己升。3. 让 Wrapper 认本地包三种落地方式与参数3.1 方式一手动解压 环境变量最直接适合完全离线、或者就想全局用一个 Gradle 的场景。步骤不复杂但每一步都有参数讲究。# 1) 解压到固定位置 unzip gradle-8.0.2-all.zip -d /opt/gradle # 2) 写入环境变量Linux/macOS追加到 ~/.bashrc 或 ~/.zshrc export GRADLE_HOME/opt/gradle/gradle-8.0.2 export PATH$GRADLE_HOME/bin:$PATH # 3) 生效并验证 source ~/.bashrc gradle -vgradle -v正常会输出 Gradle 版本、Kotlin 版本、JVM 版本和 OS 信息。逻辑说明PATH里把$GRADLE_HOME/bin放前面避免系统里已有的旧版gradle抢先命中GRADLE_HOME本身不是 Gradle 强制读取的变量但很多脚本和 IDE 会读它配上有好处。参数上注意export只对当前 shell 及子进程生效写进 rc 文件才能持久。Windows 下对应的是在「系统环境变量」里新建GRADLE_HOME再把%GRADLE_HOME%\bin加进Path改完必须重开终端老终端不会刷新环境块。提示gradle -v输出的 JVM 版本如果和工程要求不符先查JAVA_HOMEGradle 8.0.2 要求 JDK 8 及以上跑 AGP 8.0 则实际需要 JDK 17版本对不上会在配置阶段直接抛Unsupported class file major version。3.2 方式二改 distributionUrl 指向本地文件推荐给团队手动配环境变量只解决「命令行能用」./gradlew仍然会去官方地址下载。真正让 Wrapper 认本地包是改gradle-wrapper.properties。# gradle/wrapper/gradle-wrapper.properties # 原值类似 # distributionUrlhttps\://services.gradle.org/distributions/gradle-8.0.2-all.zip # 改为本地 file 协议注意 Windows 下路径写法不同 distributionUrlfile\:/opt/gradle/gradle-8.0.2-all.zip distributionBaseGRADLE_USER_HOME distributionPathwrapper/dists zipStoreBaseGRADLE_USER_HOME zipStorePathwrapper/dists逻辑说明distributionUrl支持file:协议Wrapper 会直接读本地 zip 并解压到~/.gradle/wrapper/dists下不再走网络。参数上distributionBase和zipStoreBase保持默认GRADLE_USER_HOME即可改它们会让缓存散落各处团队协作时反而难排查。注意file:后面是冒号加斜杠Windows 写成file\:/D\:/tools/gradle-8.0.2-all.zip反斜杠要转义这是 properties 文件的语法要求不是笔误。团队里把这行改成内网共享路径所有人./gradlew都走本地比每人配一遍环境变量省事。3.3 方式三预置到 GRADLE_USER_HOME 缓存目录CI 友好CI 环境不方便改工程文件也不想每次解压可以直接把包塞进 Wrapper 的缓存布局里。Wrapper 的缓存路径有固定规则~/.gradle/wrapper/dists/gradle-8.0.2-all/hash/hash是distributionUrl的 MD5 编码不同 URL 算出的 hash 不同所以这招要配合固定 URL 使用。# 先让 Wrapper 跑一次哪怕失败生成 hash 目录 ./gradlew --version || true # 找到生成的 hash 目录 ls ~/.gradle/wrapper/dists/gradle-8.0.2-all/ # 输出类似7x9k2m...一串 32 位 hash # 把本地 zip 放进去并解压出 gradle-8.0.2 目录 HASH_DIR$(ls -d ~/.gradle/wrapper/dists/gradle-8.0.2-all/*/ | head -1) cp gradle-8.0.2-all.zip $HASH_DIR unzip -q gradle-8.0.2-all.zip -d $HASH_DIR # 关键创建一个 .ok 标记文件Wrapper 见到它才认为下载完成 touch $HASH_DIR/gradle-8.0.2-all.zip.ok逻辑说明Wrapper 判断「已下载」的依据不是 zip 存在而是同目录下存在zip名.ok标记文件缺了它照样重新下载这是最容易漏的一步。参数上head -1防止有多个 hash 目录时取错实际环境如果只有一个工程直接写死路径更稳。CI 里把这套逻辑写进镜像构建阶段后续构建全程离线比每次配代理稳定得多。4. 避坑与排查五条血泪记录4.1 现象gradle -v报找不到主类原因GRADLE_HOME指到了解压的父目录或者PATH里混进了旧版 Gradle 的bin。解决echo $GRADLE_HOME确认末尾是gradle-8.0.2which -a gradle看是否有多个命中把旧的从PATH里摘掉。改完重开终端别在当前 shell 里反复source试。4.2 现象Wrapper 一直卡在 Downloading改成本地 file 后仍下载原因distributionUrl改了但没清缓存Wrapper 发现缓存目录里已有半截下载或旧 hash仍按旧逻辑走。解决删掉~/.gradle/wrapper/dists/gradle-8.0.2-all/整个目录再跑让它按新 URL 重新算 hash。这一步没有后悔药缓存不清等于白改。4.3 现象解压后bin/gradle无执行权限原因从某些渠道拿到的 zip 在传输中丢了权限位或者用图形工具解压时没保留。解决chmod x /opt/gradle/gradle-8.0.2/bin/gradle顺手把bin下所有脚本都加上。判断方法ls -l bin/gradle看有没有x没有就是这个问题。4.4 现象构建报Unsupported class file major version 61原因JDK 版本和 Gradle/AGP 不匹配61 对应 JDK 17说明工程要求 17 但当前JAVA_HOME指向了更低版本或者反过来 Gradle 8.0.2 跑在过新的 JDK 上。解决java -version和gradle -v里的 JVM 对照AGP 8.0 场景统一到 JDK 17改JAVA_HOME后重开终端。4.5 现象团队里有人能跑有人不能报 zip 损坏原因共享路径上的 zip 被不完整拷贝或者file:路径里有空格没转义。解决先unzip -t gradle-8.0.2-all.zip校验完整性路径含空格时在 properties 里用%20编码。这类问题排查起来像黑匣子最省事的做法是统一放一个无空格、无中文的路径。5. 进阶用校验和与 init 脚本把版本钉死下载来源不可控时光看文件名不够得校验。官方每个发行版都提供.sha256文件落地前对一遍能挡掉大部分半截包和篡改包。# 计算本地包的 sha256与官方 .sha256 文件内容比对 sha256sum gradle-8.0.2-all.zip # 官方校验文件通常长这样此处为格式示意实际值以官方发布为准 # 64位十六进制 gradle-8.0.2-all.zip逻辑说明sha256sum输出第一列是摘要第二列是文件名和官方文件逐字符比对即可。参数上没有花活但要注意别用md5sum凑合校验强度不够。校验通过再解压能避免「解压到一半报 unexpected end of file」这种浪费时间的翻车。另一个值得养成的习惯是用init.d脚本统一仓库和缓存配置。gradle-8.0.2-all.zip解压后自带init.d目录往里放一个init.gradle所有工程都会自动应用不用每个项目改一遍。// /opt/gradle/gradle-8.0.2/init.d/cache.gradle // 统一构建缓存目录避免每个工程各存一份 gradle.projectsLoaded { rootProject { buildCache { local { directory new File(gradle.gradleUserHomeDir, build-cache) } } } }逻辑说明projectsLoaded在工程加载后触发rootProject里配buildCache.local.directory把缓存集中到GRADLE_USER_HOME/build-cache多工程切换时命中率明显提升。参数上gradle.gradleUserHomeDir是 Gradle 内置属性别硬编码绝对路径换机器就失效。这类 init 脚本适合放团队统一镜像里新人拉下来就带好配置。我现在的习惯是任何一次拿到发行包先sha256sum对一遍再unzip -t验完整性最后才往GRADLE_HOME里放。这三步走完再配 Wrapper基本不会再被「下载到一半」「解压损坏」「版本对不上」这三类问题反复消耗。希望帮到你。本文还有配套的精品资源点击获取
