今天把一个新人的项目拉到我电脑上想先跑一次构建看看环境结果 Android Studio 还在加载阶段就直接弹了一行红字Could not install Gradle distribution from https://services.gradle.org/distributions/gradle-8.7-bin.zip。后面还跟着一个java.net.SocketTimeoutException: Read timed out。说实话这个报错我一年里少说也要遇见七八回每次都是不同的人、不同的电脑但报错文本几乎一模一样。如果你也是第一次遇到先别急着怀疑项目代码也不要去折腾 JDK 版本。这个错误的本质是Android Studio 在打开项目的时候发现本地没有对应的 Gradle 版本于是想去官方服务器下载结果下载超时了。也就是说项目本身大概率没问题问题出在Gradle 发行包拉不下来这一环。接下来我会把排查思路、镜像源替换、离线包方案、超时参数调整这些完整写一遍照着做基本都能救回来。1. 报错为什么会出现在“打开项目”这一步很多人看到这个报错的第一反应是去查 build.gradle查 dependencies甚至怀疑是不是 AGP 和 Gradle 版本不兼容。但等你真正把项目拿到手会发现很多代码是零改动就能编译的问题全出在初始化阶段。1.1 四个最容易踩中的触发时机根据我近几年的排查经验这个报错集中出现在下面四种场景新电脑首次导入项目刚装完 Android Studio本地~/.gradle/wrapper/dists目录是空的项目里声明的 Gradle 版本从来没下载过。团队更新了 Gradle 版本别人把gradle-wrapper.properties里的版本从 7.5 改成 8.7你本地没有 8.7重新 Sync 时触发下载。换分支切换了不用的 Gradle 版本比如你从 master 切到 release 分支两个分支的 wrapper 版本不同也会触发。网络环境变化在公司能下载回家连 WiFi 就是超时或者公司网络本身连外网就慢下载大文件动不动断流。也就是说只要本地缓存不存在对应版本的 Gradle 发行包Android Studio 就会主动去下载。而下载这一步只要失败它就会在项目同步前报出这个错误。1.2 distributionUrl 到底是个什么角色这里要提到 Gradle Wrapper 机制。Gradle 官方推荐每个项目都带一个 wrapper它本质上是一层“引导程序”。项目里gradle/wrapper/gradle-wrapper.properties这个文件决定了当前项目要使用哪个 Gradle 版本典型内容长这样distributionBaseGRADLE_USER_HOME distributionPathwrapper/dists distributionUrlhttps\://services.gradle.org/distributions/gradle-8.7-bin.zip networkTimeout10000 validateDistributionUrltrue zipStoreBaseGRADLE_USER_HOME zipStorePathwrapper/dists其中distributionUrl就是下载地址。Android Studio 在打开项目时会读取这个地址先去GRADLE_USER_HOMEmacOS 下是~/.gradleWindows 下一般是C:\Users\用户名\.gradle里查找有没有解压好的 gradle-8.7没有就到distributionUrl指向的地址下载。networkTimeout10000这个参数很关键默认单位是毫秒也就是说 Gradle 默认给网络连接设置了 10 秒超时。官方服务器在大洋彼岸国内网络环境稍微一波动10 秒根本不够用于是就会直接抛SocketTimeoutException。1.3 其实不是项目配置坏了很多初学者会进入一个误区觉得报错带 Could not install 就认为是安装失败。实际上 Gradle 发行包根本还没开始解压安装报错发生在“下载”阶段整个环节还没到解压那一步。所以我的排查优先级一直是第一优先确认 URL 能不能访问下载速度快不快。第二优先确认本地缓存是否完整。第三优先确认网络超时参数是否过低。项目里的build.gradle、settings.gradle这些文件在这个阶段甚至都还没被读取根本轮不到它们背锅。1.4 超时、拒连、404 三种错误长得不一样同样是下载失败错误关键字不同原因往往不一样。我整理了一张对照表方便你看到报错时快速判断方向报错关键字可能原因优先处理方式SocketTimeoutException: Read timed out连接建立后服务端迟迟不返回数据换镜像源或调大超时时间ConnectException: Connection refused目标地址拒绝连接可能被防火墙或代理拦截检查系统代理、Android Studio 代理设置FileNotFoundException: ... 404distributionUrl 写错了或者这个版本号根本不存在检查 wrapper 文件里的版本号是否拼写正确SSLHandshakeException证书校验异常常见于旧版本 Gradle 新 Java升级 wrapper 版本或修正 JDK 版本Connection reset连接被中途断开网络环境不稳定重试或者换镜像源确认类型之后就可以用下面的命令做一个快速连通性测试# 测试官方地址 curl -I https://services.gradle.org/distributions/gradle-8.7-bin.zip # 测试国内镜像地址 curl -I https://mirrors.cloud.tencent.com/gradle/gradle-8.7-bin.zipWindows 上如果没装 curl可以用Invoke-WebRequestInvoke-WebRequest -Uri https://mirrors.cloud.tencent.com/gradle/gradle-8.7-bin.zip -Method Head命令能返回 HTTP 200 就说明地址可达剩下的就是下载速度问题了。2. 先把 wrapper 换成国内镜像源解决 90% 的问题当你确认问题出在下载超时最简单的方案就是把distributionUrl换成国内 CDN 镜像。这个方法不需要安装任何额外工具改一行配置就好。2.1 修改 gradle-wrapper.properties 的最稳妥步骤第一步在 Android Studio 左侧 Android 视图下展开gradle/wrapper找到gradle-wrapper.properties并双击打开。注意是gradle目录下的 wrapper 文件不是项目的build.gradle。第二步把distributionUrl这行整体替换成镜像地址。例如distributionUrlhttps\://mirrors.cloud.tencent.com/gradle/gradle-8.7-bin.zip注意原来地址里的https://中的冒号要写成https\://这个反斜杠是 properties 文件格式要求的转义规则不要手滑删掉。第三步保存文件然后回到 Android Studio点击 File - Sync Project with Gradle Files。如果点击后还是报错建议直接把项目关闭再重新打开因为 Android Studio 对 wrapper 配置有缓存不一定会立刻重新读取。2.2 国内镜像地址对照表目前我实际验证过能用且稳定的 Gradle 镜像源主要有三个镜像源地址格式腾讯云镜像https://mirrors.cloud.tencent.com/gradle/gradle-8.7-bin.zip华为云镜像https://mirrors.huaweicloud.com/gradle/gradle-8.7-bin.zip南京大学镜像https://mirror.nju.edu.cn/gradle/gradle-8.7-bin.zip替换的时候只需要把版本号换成你项目需要的版本即可比如项目要求的是 7.6.4就写gradle-7.6.4-bin.zip。有一点要提醒有些人会误把 Maven 镜像地址和 Gradle 发行包镜像混为一谈。阿里云有很多 Maven 仓库镜像但它并不提供 Gradle 发行包的稳定镜像下载。你如果在网上搜到maven.aliyun.com的地址那通常是用来加速依赖库的和gradle-8.7-bin.zip这种安装包不是同一回事。2.3 改完为什么还是在旧地址下载这是个特别常见的坑。你明明把gradle-wrapper.properties改成了腾讯云镜像但重新打开项目后仍然在访问services.gradle.org甚至还能看到下载速度极慢。这种情况十有八九是因为本地已经存在一个未下载完成的缓存目录。Gradle 在~/.gradle/wrapper/dists/gradle-8.7-bin/下会创建一个目录里面用.part或download后缀保存临时下载文件。下次再运行时会接着下载或者因为校验失败一直卡在旧地址。解决办法很简单打开缓存目录把对应版本的整个文件夹删掉。# macOS / Linux rm -rf ~/.gradle/wrapper/dists/gradle-8.7-bin # WindowsPowerShell Remove-Item -Recurse -Force $env:USERPROFILE\.gradle\wrapper\dists\gradle-8.7-bin删掉之后重新同步一次Gradle 就会重新解析distributionUrl走镜像源拉取。2.4 命令行验证是否生效配好之后我习惯先用命令行跑一次验证就不用每次都打开 Android Studio 漫长的加载界面了。在项目根目录执行# Windows gradlew.bat --version # macOS / Linux ./gradlew --version如果一切正常终端会打印出 Gradle 版本号、JVM 版本和系统信息。首次跑的时候会看到下载进度条如果速度很快说明镜像生效了。顺便说一句不要直接执行系统里安装的gradle --version因为项目里用的 gradlew 命令才会读取 wrapper 配置系统全局 Gradle 和项目 wrapper 未必是同一个版本。3. 离线包方案网络差或完全受限环境下的兜底手段镜像源确实能解决大部分问题但有些环境比这更恶劣公司内网只能访问部分域名或者干脆所有外网都要审批。这时候再怎么换镜像也没用只能走离线包方案。3.1 先准备一个离线 zip 包离线包的本质是把 Gradle 发行包下载到一个你能访问的位置比如 U 盘、共享盘、内网资源服务器然后让项目从本地读取。你需要下载和你项目 wrapper 版本完全一致的 zip 包。下载方式有几种在能正常访问外网的电脑上从https://services.gradle.org/distributions/下载。从腾讯云/华为云镜像站下载对应 URL 和上面表格相同。从同事的~/.gradle/wrapper/dists目录里复制一份。拿到 zip 包之后放到一个固定的本地路径比如D:\gradle-dist\gradle-8.7-bin.zip或~/Downloads/gradle-8.7-bin.zip。这个 zip 包建议永久保留之后每台新电脑都能用。3.2 修改 distributionUrl 指向本地文件如果你希望 gradlew 命令行也能直接使用本地 zip可以把distributionUrl改成file://协议distributionUrlfile\:///D:/gradle-dist/gradle-8.7-bin.zipmacOS 和 Linux 的语法是distributionUrlfile\:///Users/你的用户名/Downloads/gradle-8.7-bin.zipWindows 下要注意盘符前面的斜杠file:///D:/是三斜杠后紧跟盘符。如果路径里有空格最好把 zip 包挪到一个没有空格的目录下避免各种解析问题。这样改完之后Gradle 不会再走网络直接读取本地 zip 解压。整个过程基本秒完成。3.3 在 Android Studio 里选择本地 Gradle 发行版另一种方式是不改 wrapper 文件直接在 Android Studio 指定本地安装的 Gradle。打开 Android Studio 设置Settings - Build, Execution, Deployment - Build Tools - Gradle。右侧Gradle projects列表中选择你的项目然后在Gradle distribution区域选择Local Gradle distribution本地 Gradle 发行版。接着填入你已经解压好的 Gradle 目录路径比如D:\gradle-8.7。这里的前提是你已经把 zip 解压好了。Gradle zip 包解压后的目录结构是gradle-8.7\bin、gradle-8.7\lib这样一层填路径时要指向包含bin目录的上一层。3.4 手动安装 Gradle 到系统 PATH 的注意事项如果你不只是想在 Android Studio 里用还希望命令行全局能调用 Gradle可以手动安装解压 zip 到你喜欢的目录比如D:\gradle-8.7。配置系统环境变量GRADLE_HOMED:\gradle-8.7。在Path变量末尾追加%GRADLE_HOME%\binWindows或对应路径macOS/Linux。命令行执行gradle -v验证。但对大多数 Android 开发者来说我建议还是优先依赖项目自带的gradlew不要手工指定全局 Gradle。因为不同项目要求的 Gradle 版本不一样全局版本容易造成混淆。3.5 版本冲突速查表自己做离线包方案时最怕的就是拿错版本。不同 AGPAndroid Gradle Plugin版本对 Gradle 有最低版本要求这里给一张常见版本对照表AGP 版本最低 Gradle 版本7.4.x7.58.0.x8.08.1.x8.08.2.x8.28.3.x8.48.4.x8.68.5.x8.78.6.x8.78.7.x8.9如果你的离线包版本低于这些要求即使下载成功也会在后续构建阶段报错所以下载前先确认项目和插件版本要求。4. 调大超时参数与配置 HTTP 代理专治偶发断流镜像源和离线包解决的是“下载不通”的问题。但还有一种情况让人很烦躁下载能连上速度也有就是快下完的时候突然超时报Read timed out。这种偶发问题多半是默认超时时间太短造成的。4.1 Gradle 自带的网络超时项前面提到的gradle-wrapper.properties里的networkTimeout单位是毫秒默认 10000。如果你的网络稍微慢一点10 秒还没连上就直接废了。建议把它调大networkTimeout60000这个参数影响的是 wrapper 下载 Gradle 发行包时的连接超时时间单位毫秒60 秒基本能覆盖大多数慢网络场景。4.2 在 gradle.properties 中增大 read timeout除了 wrapper 下载阶段项目构建过程中还会下载各种依赖。如果依赖仓库响应慢同样会报SocketTimeoutException。这时候要改的是项目根目录下或~/.gradle/下的gradle.properties# 连接超时单位毫秒 systemProp.org.gradle.internal.http.connectionTimeout60000 # 读取超时单位毫秒 systemProp.org.gradle.internal.http.socketTimeout120000org.gradle.internal.http.socketTimeout是我强烈建议设置的一项。它控制从服务器读取数据的超时时间。默认值在不同版本里不太一样但普遍偏小加大到 120 秒基本能覆盖大文件下载场景。把这段配置放进全局~/.gradle/gradle.properties是效果最好的因为所有项目都会生效。4.3 Android Studio 的 HTTP 代理配置有些企业网络环境下访问公网必须经过 HTTP 代理。如果代理没配对Gradle 同样无法下载。打开Settings - Appearance Behavior - System Settings - HTTP Proxy根据你所在网络环境选择手动代理或自动检测填入代理地址和端口。配好之后gradlew 命令行不一定自动继承 Android Studio 的代理。你需要确认 Gradle 能获取到代理配置推荐在gradle.properties里补充systemProp.http.proxyHost代理服务器地址 systemProp.http.proxyPort端口 systemProp.https.proxyHost代理服务器地址 systemProp.https.proxyPort端口如果公司代理不需要用户名密码这些配置就够了。需要认证的话再加systemProp.http.proxyUser和systemProp.http.proxyPassword。这是标准的企业网络代理配置方式内网环境非常常见。4.4 清理缓存文件时避免误删配置改完之后如果之前下载失败过建议清理一下~/.gradle/wrapper/dists下对应目录防止断点残留导致校验错误。但这里有个反直觉的坑不要一上来就把整个~/.gradle目录删掉。因为~/.gradle/caches里可能缓存了之前项目依赖的 jar 包删掉之后又要重新下载一堆东西反而更慢。只清理wrapper/dists下面出问题的版本目录就够了。5. 特殊场景Flutter、目录迁移这些容易混淆的坑这里再单独讲几个和 Gradle 下载报错相关但乍一看风马牛不相及的场景。5.1 Flutter 项目里同样的报错Flutter 的 Android 工程本质上也是 Gradle 工程。你用 Flutter 创建项目后在android/gradle/wrapper/gradle-wrapper.properties里同样有distributionUrl。Flutter 项目常见的报错是You are applying Flutters main Gradle plugin imperatively using the apply script method这个报错和Could not install Gradle distribution有一定关联但又不完全一样。前者多出现在 Flutter 老版本项目升级到新版本时插件应用方式不同。但如果你先遇到了 Gradle 下载超时修复完之后可能还会暴露这个插件问题。处理顺序一定是先解决 Gradle 发行包拉取再处理插件的声明方式。在 Flutter 项目里排查 Gradle 下载问题注意修改android/目录下的 wrapper 文件而不是项目根目录下那个。5.2 迁移 .android 和 .gradle 目录要注意路径很多人的 C 盘很容易被 Android Studio 塞满尤其~/.android模拟器 AVD 镜像和~/.gradleGradle 缓存这两个目录特别占空间。想把它们迁移到其他盘用环境变量指定路径这在技术上没有问题但有个细节迁移完之后之前已经下载好的 Gradle 发行包缓存也要一起搬过去否则重新打开项目又会在新路径下载一次全量发行包。推荐迁移方式先把~/.gradle目录完整复制到目标盘比如D:\gradle_home。在系统中添加环境变量GRADLE_USER_HOMED:\gradle_home。重启 Android Studio。用gradlew --version验证确认走的是新路径。不要只改环境变量却不复制旧缓存。否则相当于把缓存清零所有项目第一次打开都会重新触发 Gradle 下载。5.3 修改应用图标不需要重装 Gradle搜索热词里有“androidstudio 修改 应用 图标”和 Gradle 报错放在一起容易让人产生误解。修改应用图标只是替换res/mipmap目录下图片资源属于应用资源文件变更不会触发 Gradle 重新安装也不会导致Could not install Gradle distribution。如果你在改图标之后突然遇到这个报错多半是因为你在修改的同时升级了项目依赖或清理了系统临时文件纯属时间巧合。不要为了修图标去动 Gradle 配置。6. 几年维护下来我对 Gradle 下载这条线的防御性习惯最后说点经验性的东西。Gradle 下载报错不复杂但它很消耗时间而且总是出现在你最着急构建的时候。我在实际项目中积累了几个小习惯可以让团队少踩很多坑。6.1 团队统一 wrapper 版本并固定镜像在团队协作中我会要求在代码仓库里明确锁定gradle-wrapper.properties的版本号不要今天 7.4、明天 8.7 来回切换。版本越稳定每个人本地缓存复用率越高触发下载的场景越少。同时我会在项目 README 里写清楚镜像源替换方案。新成员入职直接把改好的 wrapper 文件发给他省得他一遍遍去碰官方服务器下载。6.2 准备一份离线包放在共享网盘鉴于网络环境的不确定我强烈建议团队把常用几个版本的 Gradle zip至少包含项目当前使用版本放在一个共享位置比如企业网盘或内网共享目录。新同事入职第一件事不是让他打开 Android Studio 等构建而是先把离线包下载到本地按上一节提到的方法配置好。整个初始化过程会从半小时缩短到三分钟。6.3 遇到陌生的构建错误先从日志尾部往上读Could not install Gradle distribution这种报错Android Studio 弹窗里展示的信息往往经过简化真正的根因在日志里。在 Android Studio 的 Build 窗口里切到Build Output逐行往上回滚找到第一行出现Caused by的地方那才是问题的源头。如果日志里有SocketTimeoutException就不要去怀疑代码如果日志里有SSLHandshakeException就去查 JDK 版本如果日志里出现 404就去核对 distributionUrl 地址。这样一层层定位通常几分钟就能找到正确答案。根据我个人的经验绝大多数 Gradle 下载类报错的成本都花在“错误定位”上实际修复往往只要改一行配置。把超时参数调大、镜像源配好、离线包备好这三板斧下来基本很难再被这个问题卡住了。