Gradle 各版本下载地址大全：镜像加速、离线缓存与故障排查

Gradle 各版本下载地址大全：镜像加速、离线缓存与故障排查

发布时间：2026/9/18 16:37:02
Gradle 各版本下载地址大全：镜像加速、离线缓存与故障排查 1. 为什么一个下载能反复把人卡住1.1 先说清楚这篇东西到底解决什么问题Gradle 各版本快速下载地址大全这个标题听起来像是个资源清单但我干了这么多年构建工程越来越觉得它本质上是一份故障处理手册——因为绝大多数人搜这个词的时候电脑上都正挂着一行红色的下载失败提示而不是在悠闲地做技术选型。具体场景大概长这样你克隆了一个别人的项目敲下gradlew build终端里进度条爬到 40% 卡死不动几分钟后甩出一句could not install gradle distribution from ... reason: java.net.SocketTimeoutException。或者你在 Android Studio 里点了 Sync Project with Gradle Files然后眼睁睁看着右侧的 Build 窗口十几分钟没有新日志风扇转得像要起飞。再或者更崩溃一点你只是想把一个老项目的 Gradle 从 7.6 升到 8.7结果发现公司内网根本不通外网构建工具自己都装不上。这篇文章要做的就是把这些场景一次性理清楚各个版本的发行包去哪里取、包有几种形态该选哪种、国内有哪些稳定可用的镜像、怎么把分发文件塞进本地让 Wrapper 完全不联网、依赖仓库的镜像怎么配才不会每个项目都改一遍、以及那一堆超时和解析失败的报错到底对应什么根因。内容偏向实操代码和配置都是可以直接复制的形态做 Android、Java 后端、Flutter 的同学都能对得上号。1.2 下载慢这件事根因其实有三层很多人以为慢是一个问题实际上它是三个完全不同的问题叠在一起得分开治。第一层是Gradle 本身的发行包。Gradle 不是装一次就完了的工具它是跟着项目走的——每个项目在gradle/wrapper/gradle-wrapper.properties里指定自己要用哪个版本首次构建时由 Wrapper 去下载对应的 zip 包。这个包 bin 版大概 100MB 出头all 版接近 200MB从海外站点拉网络稍微抖动一下就是几分钟起步。第二层是项目依赖的 jar 包。这是真正的大头。一个中等规模的 Spring Boot 或 Android 项目依赖树展开后动辄几百个 jar加起来几百 MB 到 1GB 都正常。这些包来自 Maven Central、Google Maven 等仓库同样是海外站点。第三层是插件与元数据的解析。Gradle 在拉依赖之前先要去读maven-metadata.xml、.pom、.module这些描述文件确定哪个版本存在、有哪些传递依赖。这些请求数量极多、单个极小是最容易被超时打断的环节也是ModuleVersionResolveException这类报错的高发区。把这三层分清楚之后策略就很明确了发行包尽量走一次性离线落地依赖包走镜像仓库元数据解析靠合理的仓库声明顺序 缓存复用。后面几章基本就是围绕这三条线展开。1.3 这篇内容适合谁如果你是完全没接触过 Gradle 的新手第一章到第三章能帮你把概念和版本对应关系理清楚照着做不会踩太离谱的坑如果你已经被同步超时折磨过好几轮第四、五、七章是重点里面有几个技巧比如手工构造 Wrapper 缓存目录、用初始化脚本全局注入镜像能省掉大量重复劳动如果你在做团队级的基础设施第六章的版本目录和第八章的经验清单更值得看那部分决定了你的项目在别人机器上能不能一键跑起来。需要提前说明的是下面涉及的所有站点地址、版本号、兼容性关系都是基于公开的官方文档和常见社区实践整理的具体用的时候请以你访问到的实际目录结构为准。版本这东西更新太快我写的时候是对的你读的时候可能已经变了。2. 动手之前先搞清楚你要下载的到底是哪个包2.1 bin、all、src 三种发行包的区别Gradle 官方为每个版本提供三种主要的分发文件命名非常规律文件名体积量级内容适用场景gradle-X.Y-bin.zip约 100–130MB可执行程序、核心库无源码与文档日常构建、CI 环境首选gradle-X.Y-all.zip约 180–220MB在 bin 基础上包含源码与 API 文档需要在 IDE 里跳进 Gradle 内部源码调试gradle-X.Y-src.zip约 60–80MB仅源码研究实现、二次开发选哪个的答案很直接除非你明确要在 IDEA 里 F3 跳进 Gradle 的类实现里看逻辑否则一律选 bin。我见过不少人无脑用 all理由是大而全肯定没错结果就是每个项目首次同步多下 100MBCI 流水线上十几个 Job 并行跑白白多出的流量和磁盘占用非常可观。还有个容易被忽略的点all包在解压后会多出src目录如果你在公司内网做统一分发多出来的这部分会让镜像目录体积膨胀接近一倍。对纯构建场景来说这部分内容一次都不会被读到。2.2 校验文件和版本清单文件每个 zip 旁边都有一个同名的.sha256文件内容就是一串哈希值。别跳过这一步理由有三个一是能确认文件没在下载过程中被截断大文件断点续传出问题是常事二是内网镜像同步偶尔会同步到残缺文件三是 Wrapper 支持distributionSha256Sum参数做强制校验配置之后如果哈希对不上会直接报错终止比在构建到一半时冒出诡异的类找不到要好得多。版本清单文件通常叫versions.all或类似的索引文件记录了当前所有可用版本号。你在写脚本批量同步镜像时用它来遍历比自己去猜版本号靠谱得多。另外官方还提供current和release-candidate这类固定别名用得不多但知道有这么个东西看到别人配置里写别名时不会懵。2.3 Java 版本与 Gradle 版本的对应关系这是第二个高频踩坑点。Gradle 本身跑在 JVM 上每个 Gradle 版本对 JDK 有明确的支持区间装错了就是一句Unsupported class file major version或者一堆莫名其妙的 ASM 报错。下面这张表是基于官方兼容性说明整理的常用区间Gradle 版本支持的 JDK 范围运行 Gradle 自身6.x8 – 157.0 – 7.28 – 167.3 – 7.68 – 198.0 – 8.48 – 198.5 – 8.78 – 218.8 – 8.98 – 228.10 – 8.148 – 239.0 及以上17 – 24注意这里说的是运行 Gradle 自身所需的最低/最高 JDK。你项目里编译产物用的 Java 版本是另一回事通过sourceCompatibility、targetCompatibility或 toolchain 单独控制。两件事别混。看到your build is currently configured to use java 21.0.4 and gradle 8.8这类提示先别慌多数时候它说的是Android Gradle Plugin 与该 JDK 的组合有问题而不是 Gradle 本身不支持。Android 侧还有一层 AGP 与 Gradle 的对应关系比如 AGP 8.x 基本要求 Gradle 8.x 起步排查时要三条线一起看JDK 版本、Gradle 版本、AGP 版本。2.4 一个我反复验证过的版本选择原则不要在项目里追最新版。Gradle 的大版本更新节奏挺快小版本之间也可能有行为变更比如 8.x 里对buildDir的废弃、对配置缓存的收紧。我的做法是新项目用当前次新的大版本里最新的小版本比最新版晚一个身位存量项目只在有明确收益时升级比如需要 JDK 21 支持、需要某个新 API团队项目版本号统一写进版本目录文件不允许各人在自己机器上私改。这个原则看起来保守但它能过滤掉大量升级完发现某个插件还没适配的问题。3. 各版本下载地址的整理逻辑与速查方法3.1 官方分发地址的命名规律与其背地址不如记规律。官方分发地址的结构非常固定https://services.gradle.org/distributions/gradle-版本号-包类型.zip把你想要的版本号和包类型填进去就是完整地址。比如 8.7 版本的 bin 包就是版本号填8.7、包类型填bin。理解了这个结构你就有了任意版本的下载能力而不需要一份别人整理好、随时可能过期的清单——这也是这份大全最核心的价值所在。在gradle-wrapper.properties里写这个地址时有个必须注意的细节distributionUrlhttps\://services.gradle.org/distributions/gradle-8.7-bin.ziphttps:后面的冒号必须转义成\:。原因是 properties 文件格式里冒号是键值分隔符不转义的话解析器会在冒号处断开导致 URL 被截断成一个奇怪的值。这个坑非常隐蔽因为不转义时 Gradle 通常不会立刻报URL 格式错误而是给你一个超时或者 404让你往网络方向查半天。3.2 国内镜像的路径规律国内几家云厂商提供了 Gradle 发行包的镜像路径规律同样是固定前缀加同名文件镜像来源地址前缀形式腾讯云https://mirrors.cloud.tencent.com/gradle/华为云https://mirrors.huaweicloud.com/gradle/其他公共镜像站通常在/gradle/或/gradle/distributions/目录下用法就是把官方域名整段替换掉后面的gradle-8.7-bin.zip原样保留distributionUrlhttps\://mirrors.cloud.tencent.com/gradle/gradle-8.7-bin.zip提示镜像站的同步存在延迟刚发布几天的新版本可能在镜像上还看不到。遇到 404 先回官方地址确认版本是否存在再判断是不是镜像没同步。别反过来先怀疑自己写错了。我在实际使用中总结出一条判断经验镜像站上如果连gradle-X.Y-bin.zip.sha256这个校验文件都能拿到说明这个版本同步完整只有 zip 没有 sha256往往意味着同步还在进行中这种时候下下来的包有概率是残缺的别用。3.3 一个可以自助生成地址的小脚本既然地址是拼出来的那就可以脚本化。下面这段 bash 用来生成一批你关心的版本下载命令同步到内网镜像目录时很好用#!/usr/bin/env bash # 批量生成下载命令按需修改版本列表与镜像前缀 MIRRORhttps://mirrors.cloud.tencent.com/gradle VERSIONS(7.6.4 8.0.2 8.5 8.7 8.10.2 8.14.3) PKGbin for v in ${VERSIONS[]}; do filegradle-${v}-${PKG}.zip echo curl -fL --retry 3 -o ${file} ${MIRROR}/${file} done-f让 curl 在 404 时直接失败而不是把错误页写成文件--retry 3处理偶发断连-L跟随跳转。这三个参数缺一个你都会在后续校验时收到惊喜。对应的 Windows PowerShell 版本$mirror https://mirrors.cloud.tencent.com/gradle $versions (7.6.4,8.0.2,8.5,8.7,8.10.2,8.14.3) foreach ($v in $versions) { $file gradle-$v-bin.zip Invoke-WebRequest -Uri $mirror/$file -OutFile $file -MaximumRetryCount 3 }3.4 版本速查需要关注哪几个点不用把每个版本都记下来关注这几个维度就够了你项目当前用的版本直接看gradle-wrapper.properties这是硬约束目标 JDK 版本要求的最低 Gradle 版本要跑 JDK 21至少得 8.5你用的 AGP 版本要求的 Gradle 区间这个必须查 AGP 的官方说明不能猜团队其他项目在用的版本尽量收敛能少维护一个版本就少一个。把这四个约束交叉一下通常能选的版本就剩一两个了。这时候再按次新大版本 最新小版本的原则挑基本不会错。4. 四种落地姿势从手动安装到完全离线4.1 姿势一下载发行包手动安装并配置环境变量这是最原始也最可控的方式适合需要在机器上长期使用同一个 Gradle 版本的场景比如你经常用命令行跑gradle而不是gradlew。Windows 上的步骤把gradle-8.7-bin.zip解压到一个路径不含空格和中文的目录比如D:\devtools\gradle-8.7。路径里有空格是很多构建脚本翻车的原因别图省事放Program Files。新建环境变量GRADLE_HOME值指向解压出来的目录注意是解压后的gradle-8.7这一层不是它的父目录很多人这里多一层或少一层。在Path里追加%GRADLE_HOME%\bin。打开新的命令行窗口必须新开旧窗口不会读到新环境变量执行gradle -v。macOS / Linux 上的步骤sudo mkdir -p /opt/gradle sudo unzip gradle-8.7-bin.zip -d /opt/gradle # 加入 shell 配置注意按你的 shell 选对应文件 echo export GRADLE_HOME/opt/gradle/gradle-8.7 ~/.bashrc echo export PATH$GRADLE_HOME/bin:$PATH ~/.bashrc source ~/.bashrc gradle -vgradle -v的输出里会同时告诉你 Gradle 版本、Kotlin 版本、JVM 版本、操作系统信息。这四项是排查问题的黄金信息遇到任何构建问题先把这个输出贴出来能省掉一半的来回问询。注意不建议在系统里同时配置多个 Gradle 版本到 PATH。真要切换用版本管理工具或者直接写绝对路径调用别搞两个都叫gradle的命令互相打架。4.2 姿势二改 Wrapper 配置让项目走镜像这是日常最常用的方式改一个文件就行# gradle/wrapper/gradle-wrapper.properties distributionBaseGRADLE_USER_HOME distributionPathwrapper/dists distributionUrlhttps\://mirrors.cloud.tencent.com/gradle/gradle-8.7-bin.zip distributionSha256Sum把对应 sha256 文件的内容粘过来 zipStoreBaseGRADLE_USER_HOME zipStorePathwrapper/dists networkTimeout60000 validateDistributionUrltrue几个参数逐个说distributionPath/zipStorePath决定包解压和 zip 存哪儿默认都在用户目录下的.gradle里。如果你的系统盘空间紧张可以把它指到别的大盘上distributionSha256Sum加上之后会强校验。强烈建议加这是防止拿到残缺包的最有效手段networkTimeout毫秒为单位默认值偏小网络差的环境下调大能减少无谓失败validateDistributionUrl默认开启会在下载前先探测 URL 是否可达能更早暴露地址写错的问题。需要提醒一点这个文件一旦提交到仓库就影响到所有协作者。所以在团队项目里改镜像地址之前最好确认一下如果有些同事处在一个访问镜像站也不通畅的环境你是不是该提供两套配置比如用-P参数传入地址。4.3 姿势三手工构造 Wrapper 缓存目录实现真正零联网这是我最想推荐的一个技巧在内网环境和 CI 缓存预热时特别好用。原理是Wrapper 下载完成后会把 zip 和解压结果放在一个由distributionUrl哈希出来的固定目录里并在旁边放一个标记文件表示这个包已经就绪。只要我们把文件按同样的结构放好并造出标记文件Wrapper 就会直接跳过下载环节。目录结构长这样~/.gradle/wrapper/dists/ └── gradle-8.7-bin/ └── URL的哈希值/ ├── gradle-8.7-bin.zip ├── gradle-8.7-bin.zip.ok ← 关键标记文件 └── gradle-8.7/ ├── bin/ ├── lib/ └── ...那个哈希值是怎么算的是对完整的 distributionUrl 字符串做 MD5取十六进制大写。在 Linux/macOS 上printf %s https://mirrors.cloud.tencent.com/gradle/gradle-8.7-bin.zip | md5sumWindows PowerShell 版本$url https://mirrors.cloud.tencent.com/gradle/gradle-8.7-bin.zip $md5 [System.Security.Cryptography.MD5]::Create() $hash $md5.ComputeHash([System.Text.Encoding]::UTF8.GetBytes($url)) ([System.BitConverter]::ToString($hash)).Replace(-,)提示哈希是基于完整 URL 字符串算的所以你把distributionUrl从官方地址改成镜像地址之后对应的缓存目录名也会变需要重新放一份。这是很多人明明放好了还是不认的根本原因。完整的落地脚本可以这样写#!/usr/bin/env bash set -euo pipefail URLhttps://mirrors.cloud.tencent.com/gradle/gradle-8.7-bin.zip VERgradle-8.7 ZIPgradle-8.7-bin.zip BASE$HOME/.gradle/wrapper/dists/gradle-8.7-bin HASH$(printf %s $URL | md5sum | awk {print toupper($1)}) TARGET$BASE/$HASH mkdir -p $TARGET cp $ZIP $TARGET/ unzip -q -o $TARGET/$ZIP -d $TARGET touch $TARGET/$ZIP.ok # 必须最后做避免中途失败留下已完成假象 echo done - $TARGETtouch那一步放在最后是有讲究的如果先创建标记文件再解压中途失败了Wrapper 会认为缓存完好然后在一个残缺目录上跑构建报出来的错会非常离谱。等所有步骤都成功了再落标记这是顺序上的硬要求。4.4 姿势四依赖仓库换镜像这个才是提速大头发行包解决的是工具本身依赖仓库解决的才是项目内容。Gradle 的仓库声明可以在三个层级做项目级每个项目的settings.gradle或build.gradle里改灵活但重复用户级~/.gradle/init.gradle或~/.gradle/init.d/下放脚本一次配置全局生效环境变量级通过GRADLE_USER_HOME指向不同的用户目录实现换环境换配置。我推荐用户级理由很简单你不可能记得住每个项目都去改仓库地址而一个初始化脚本能管住你机器上所有项目。具体写法放在下一章。4.5 四种姿势怎么选姿势适用场景一次性成本后续维护成本手动安装 环境变量命令行常用、CI 基础镜像构建中低改 Wrapper 配置日常开发单个项目低低但需随项目走手工构造缓存目录内网、CI 预热、完全离线高极低依赖仓库镜像所有场景提速最明显低低实际项目里我基本是三加四组合Wrapper 走镜像 依赖仓库走镜像 CI 镜像里预置常用版本的缓存目录。三层一起上新机器上从 clone 到构建成功通常能压到两三分钟以内。5. 依赖加速仓库镜像的配置方式与顺序逻辑5.1 仓库声明的顺序会决定解析结果Gradle 在找依赖时是按repositories {}里声明的先后顺序依次查找的。某个坐标如果在第一个仓库找到了它就不会继续往后找。这个机制带来两个后果一是镜像要放前面否则请求永远先打到慢的源上二是顺序会影响同名构件——如果两个仓库里存在相同坐标但内容不同的构件这种情况在某些第三方聚合仓库里真实存在先声明的那个胜出。所以配置镜像不是加进去就行位置很关键。一个合理的顺序是内网私服在前、国内公共镜像居中、官方源兜底在后。// settings.gradle 里统一管理 dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS) 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 } google() mavenCentral() } }RepositoriesMode.PREFER_SETTINGS这个设置的含义是优先使用 settings 里声明的仓库忽略子模块自己声明的。它的作用是防止某个第三方模块在它自己的脚本里硬编码一个海外仓库把你精心配好的镜像顺序打乱。用FAIL_ON_PROJECT_REPOS也可以更严格但遇到不规范的第三方库时容易直接构建失败团队协作场景下PREFER_SETTINGS更稳妥。5.2 用 init.gradle 做全局注入这是我最常用的方式写在~/.gradle/init.gradle// ~/.gradle/init.gradle allprojects { buildscript { repositories { maven { url https://maven.aliyun.com/repository/gradle-plugin } maven { url https://maven.aliyun.com/repository/public } } } repositories { maven { url https://maven.aliyun.com/repository/public } maven { url https://maven.aliyun.com/repository/google } } }这段脚本会被注入到每一个构建里包括buildscript块插件解析和普通依赖解析覆盖面最广。有个细节值得说buildscript和普通repositories是两套独立的仓库列表很多人只改了后者结果插件下载还是慢——因为插件是从前者解析的。别漏。settings.gradle的pluginManagement又管着另一条路径插件市场式的插件声明。三处都照顾到才算完整// settings.gradle pluginManagement { repositories { maven { url https://maven.aliyun.com/repository/gradle-plugin } gradlePluginPortal() google() } }提示init.d/目录下所有.gradle文件都会被执行可以用它来做分环境切换——比如dev-repos.gradle和ci-repos.gradle通过环境变量判断后apply from:引入。比在一个大文件里写 if-else 清晰得多。5.3 缓存、离线模式和缓存清理Gradle 会把下载过的依赖存到~/.gradle/caches/modules-2/下。这个缓存是按构件 哈希组织的同一个依赖被多个项目使用只存一份这点比早期版本优秀不少。常用的几个开关# 完全离线只用缓存网络请求一个都不发 ./gradlew build --offline # 强制刷新忽略缓存重新解析排查明明更新了版本却不生效 ./gradlew build --refresh-dependencies # 只输出依赖树不下任何东西排查依赖冲突 ./gradlew :app:dependencies --configuration releaseRuntimeClasspath--refresh-dependencies是把双刃剑。它能看到最新的版本信息但代价是把元数据全部重新拉一遍在慢网络下可能直接卡死。我的习惯是先--offline试很多时候缓存里就有不行再联网联网时也只针对特定模块刷新./gradlew build --refresh-dependencies -PrefreshOnlycom.example:lib然后在脚本里读这个参数做精细化控制。虽然要多写几行但比全量刷新省下太多时间。缓存出问题时的清理要精准不要一上来就rm -rf ~/.gradle——那等于把你所有项目的依赖全部重新下载一遍。正确做法是定位到具体模块目录删掉# 只删某个模块的缓存 rm -rf ~/.gradle/caches/modules-2/files-2.1/com.example/lib # 怀疑元数据缓存坏了删这部分 rm -rf ~/.gradle/caches/modules-2/metadata-*删完之后 Gradle 会自动重建只会重新拉那几个构件。5.4 Gradle 和 Maven 到底差在哪既然热度里这个词一直挂着顺手把差异说清楚因为它直接影响你怎么理解下载慢这件事维度MavenGradle配置形式XML声明式结构固定Groovy/Kotlin DSL可编程构建模型固定生命周期compile/package/install任务图task graph按需执行增量构建支持有限完善配合构建缓存效果明显依赖范围scope 概念固定configuration 可自定义更灵活缓存位置~/.m2/repository~/.gradle/caches/modules-2学习曲线平缓但改不动陡峭但天花板高老项目迁移成本—高尤其是定制插件多的项目理解这个差异的价值在于Maven 的依赖是扁平声明你在 pom 里写什么就下什么Gradle 的依赖解析过程更动态会受仓库顺序、版本约束、动态版本号、依赖替换规则影响。所以 Gradle 的解析失败往往比 Maven 更难猜——同一个坐标Maven 拉不到就是拉不到Gradle 可能是因为前面某个仓库返回了一个元数据存在但构件不存在的结果导致它提前中止了。6. 版本目录把版本号从各处收拢到一个文件6.1 为什么需要 libs.versions.toml版本目录Version Catalog解决的是一个老问题依赖版本散落在各个模块的构建脚本里升级一个库要改十几处还容易漏。它的做法是抽出一个gradle/libs.versions.toml文件[versions] kotlin 1.9.24 agp 8.5.2 retrofit 2.11.0 coroutines 1.8.1 [libraries] retrofit-core { module com.squareup.retrofit2:retrofit, version.ref retrofit } retrofit-gson { module com.squareup.retrofit2:converter-gson, version.ref retrofit } coroutines-core { module org.jetbrains.kotlinx:kotlinx-coroutines-core, version.ref coroutines } [plugins] android-application { id com.android.application, version.ref agp } kotlin-android { id org.jetbrains.kotlin.android, version.ref kotlin }然后在构建脚本里用生成的访问器// build.gradle.kts plugins { alias(libs.plugins.android.application) alias(libs.plugins.kotlin.android) } dependencies { implementation(libs.retrofit.core) implementation(libs.retrofit.gson) implementation(libs.coroutines.core) }好处很实际升级 Retrofit 只改[versions]里的一行所有引用它的模块自动跟着变。而version.ref这种引用方式还能保证同一个库的多个构件版本完全一致避免出现retrofit是 2.11 而converter-gson是 2.9 这种低级错配。6.2 和下载地址有什么关系关系大了。版本目录本身不改变下载行为但它把版本这个变量集中管理之后你就获得了一个可控的升级点。比如你要验证换到某个版本能不能解决超时问题改一行、跑一次不用满项目搜索替换。而且在离线场景下版本目录配合内网私服特别好用你只要同步目录里出现的这些坐标不需要同步整个 Maven Central。这在构建一个干净的内网镜像时能省掉几个数量级的工作量。6.3 Flutter 项目里的插件声明坑Flutter 项目经常遇到一条警告大意是你正在用 apply 脚本的方式命令式地引入 Flutter 的 Gradle 插件这种方式已废弃请迁移到声明式的 plugins 块。这条警告的根因在android/settings.gradle和android/app/build.gradle里的历史写法// 老写法会触发警告 apply from: $flutterRoot/packages/flutter_tools/gradle/flutter.gradle新版 Flutter 模板改成了// android/settings.gradle 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() } } plugins { id dev.flutter.flutter-plugin-loader version 1.0.0 id com.android.application version 8.5.2 apply false id org.jetbrains.kotlin.android version 1.9.24 apply false }迁移过程中有两个高频问题一是local.properties里flutter.sdk没配或者路径带反斜杠Windows 上尤其容易导致includeBuild找不到目录二是迁移后插件的加载时机变了某些在apply from之后立刻读取插件配置的代码会失效需要挪到plugins块之后再执行。提示迁移时先把原来的apply from注释掉、新版块加上去跑一次完整构建确认通过再删注释。中间态留着出问题好回退。7. 常见报错排查手册7.1 SocketTimeoutException下载超时完整报错通常长这样Could not install Gradle distribution from https://services.gradle.org/distributions/gradle-8.7-bin.zip. Reason: java.net.SocketTimeoutException: Read timed out排查顺序建议这样走先确认地址可达。用浏览器或者curl -I直接访问那个 URL看返回码。如果连不上就是网络层面的问题换镜像地址换镜像后确认 hash 目录变化。前面说过URL 变了哈希就变了如果之前手工放过缓存需要重新放调大超时。在gradle-wrapper.properties里加networkTimeout120000同时在gradle.properties里加 JVM 层面的超时# gradle.properties systemProp.org.gradle.internal.http.connectionTimeout120000 systemProp.org.gradle.internal.http.socketTimeout120000极端情况下手工落地。用第 4.3 节的方法把包装进缓存目录一劳永逸。7.2 ModuleVersionResolveException依赖解析不到报错形如Caused by: org.gradle.internal.resolve.ModuleVersionResolveException: Could not resolve gradle:gradle:8.7.这类问题的关键线索是看冒号前面的坐标属于谁。如果坐标是你项目自己的依赖说明仓库里确实没有这个版本或者镜像还没同步如果坐标是gradle:gradle这种说明是构建期插件在解析 Gradle 自身的分发通常意味着插件声明的仓库里缺了对应源。处理办法到镜像站上手动访问对应的目录确认maven-metadata.xml存在且里面列出了这个版本检查是不是pluginManagement里的仓库列表少了一家如果是私服确认私服有没有做代理远程仓库的配置有些私服只代理了 central没代理 google。7.3 Java 版本不匹配典型提示会明确告诉你用了什么 JDK、什么 Gradle 版本。处理路线是# 先看当前用的是什么 ./gradlew -v # 明确指定 JDK 运行 Gradle而不是靠 JAVA_HOME 猜 ./gradlew build -Dorg.gradle.java.home/path/to/jdk17或者在gradle.properties里固定org.gradle.java.homeC:\\Program Files\\Java\\jdk-17Windows 路径里的反斜杠要双写或改成正斜杠。这一步之外更推荐的做法是给项目配toolchain让 Gradle 自己去管理编译用的 JDK而不是依赖本机环境kotlin { jvmToolchain(17) }这样即使本机装的是 JDK 21Gradle 也会自动定位或下载一个 17 来编译版本一致性问题从根上解决。7.4 其他几个高频小毛病现象常见根因处理办法构建卡在 Waiting to acquire shared lock上一个进程没退干净./gradlew --stop停掉守护进程缓存目录里有.part文件下载中断残留半成品删掉对应模块目录重新拉提示 wrapper 校验失败distributionSha256Sum与实际不符重新获取 sha256 值或暂时移除该配置换镜像后仍然很慢只改了 Wrapper没改依赖仓库按第 5 章配置init.gradle依赖树里出现同一个库多个版本传递依赖版本冲突用dependencies任务看树加resolutionStrategy强制统一内网构建报 DNS 解析失败内网不通外网但脚本里还留着官方地址全量替换为内网私服地址7.5 一个通用的排查动作模板遇到任何构建问题我习惯按这四步走五次里能解决四次./gradlew --version确认工具链版本./gradlew build --offline看是不是纯网络问题离线能过说明是下载环节--info或--debug跑一次看卡在哪一步。--info的输出量大但可读--debug大到需要重定向到文件再搜关键字定位到具体模块后只删那一个模块的缓存重试。./gradlew assembleDebug --info build-info.log 21 # 然后在 build-info.log 里搜 Downloading / Resolving / FAILED这个日志文件在跟同事协作排查时也特别有用直接甩日志比来回描述现象高效得多。8. 我踩过的坑和几条经验把所有内容收束到几条我实际用下来最有价值的经验上。第一条把工具下载和依赖下载当成两件事处理。早期我总是混着看一个项目同步慢第一反应是网不行。后来才意识到工具包只有一次下载依赖包才是每天都要碰的。工具包一次搞定离线缓存依赖包靠镜像两条线各自优化效果比笼统地想办法加速好太多。第二条手工构造 Wrapper 缓存目录这一步值得花半小时学会。它带来的收益远超预期CI 镜像里预置三五个常用版本新流水线冷启动时间能从五六分钟降到几十秒团队新人入职时把缓存目录拷过去不用等首次同步。唯一的门槛是要算对哈希、放对文件名、最后落标记文件注意顺序。第三条镜像地址永远配在用户级不要配在项目级。项目级的配置要跟着代码走一旦提交上去就变成对所有人的强制约束而你并不知道所有人的网络环境。用init.gradle管住自己机器项目里保留官方地址这样代码在任何环境都是标准形态本地加速是你的私事。第四条缓存不要无脑删。我见过同事遇到依赖问题第一反应就是rm -rf ~/.gradle然后花二十分钟重新下载所有东西问题还不一定解决。精准定位到模块目录删是快十倍的方案。判断该删哪一层的方法也很简单看报错里的坐标直接映射到modules-2/files-2.1/group/artifact这个路径。第五条版本号和 JDK 的关系抄一份表放在项目 README 里。这条听起来很土但它真的省事。新同事接手项目最容易犯的错就是本机 JDK 版本和项目不匹配README 里写清楚本项目要求 JDK 17 Gradle 8.7 AGP 8.5.2比等着别人来问要有用得多。配上 toolchain 配置就更稳了让工具自己去满足约束而不是靠人的记忆。第六条离线构建能力是构建系统的及格线不是加分项。一个项目如果必须在联网状态下才能构建那它在 CI 断网、网络抖动、上游仓库临时不可用的时候就会直接瘫痪。花点时间把发行包离线化、把依赖缓存预热好这件事的价值在平时看不出来出问题时能救命。最后补一个容易被忽略的小细节~/.gradle这个目录默认在系统盘Windows 上尤其容易撑爆。如果你的开发机系统盘不大用GRADLE_USER_HOME环境变量把它挪到数据盘配合第 4.3 节的缓存构造方法一起用既解决了空间问题又保留了离线能力。这个环境变量对 Gradle 的所有缓存路径wrapper、modules、daemon 日志都生效挪一次省心很久。