1. 问题现象与背景分析最近在Android Studio中创建新项目时不少开发者遇到了Could not install Gradle distribution from... Connection reset的错误提示。这个报错通常发生在首次创建项目或更新Gradle版本时控制台会显示类似如下的错误信息Could not install Gradle distribution from https://services.gradle.org/distributions/gradle-8.4-bin.zip. Connection reset java.net.SocketException: Connection reset这个问题的本质是Android Studio无法从Gradle官方服务器下载所需的Gradle发行包。在国内开发环境下这个问题尤为常见主要原因包括网络连接问题Gradle官方服务器位于海外国内直接访问可能会遇到网络不稳定或被重置的情况代理配置不当如果开发者使用代理网络但未正确配置Android Studio的代理设置本地Gradle缓存损坏之前下载的Gradle包不完整或损坏防火墙/安全软件拦截某些安全软件可能会阻止Gradle的下载请求2. 解决方案总览针对这个问题我总结了几种有效的解决方法开发者可以根据自己的网络环境和项目需求选择最适合的方案使用国内镜像源替换Gradle官方下载地址推荐手动下载Gradle发行包并配置本地路径检查并正确配置网络代理清理Gradle缓存并重新下载下面我将详细介绍每种解决方案的具体实施步骤和注意事项。3. 使用国内镜像源解决方案3.1 修改gradle-wrapper.properties文件这是最推荐且一劳永逸的解决方案。Gradle的下载地址配置在项目目录下的gradle/wrapper/gradle-wrapper.properties文件中打开你的Android Studio项目在项目面板中找到gradle/wrapper/gradle-wrapper.properties文件修改distributionUrl属性将官方地址替换为国内镜像地址原内容通常类似distributionUrlhttps\://services.gradle.org/distributions/gradle-8.4-bin.zip修改为阿里云镜像distributionUrlhttps\://mirrors.aliyun.com/gradle/gradle-8.4-bin.zip或者腾讯云镜像distributionUrlhttps\://mirrors.cloud.tencent.com/gradle/gradle-8.4-bin.zip3.2 注意事项确保gradle版本号与实际需要的版本一致修改后需要同步Gradle点击Android Studio右上角的Sync Now如果项目中有多个模块确保所有模块的gradle-wrapper.properties文件都进行了修改国内镜像可能会有轻微延迟建议选择离自己地理位置较近的镜像源4. 手动下载Gradle发行包方案4.1 手动下载步骤如果镜像源方案不适用可以尝试手动下载访问Gradle官方发布页面https://gradle.org/releases/找到与项目所需的完全相同的版本注意-bin.zip和-all.zip的区别下载对应的zip文件将下载的文件放入Gradle缓存目录Windows:C:\Users\你的用户名\.gradle\wrapper\dists\gradle-x.x-bin\随机字符串\macOS/Linux:~/.gradle/wrapper/dists/gradle-x.x-bin/随机字符串/4.2 目录结构说明Gradle的缓存目录结构需要注意每个版本对应一个独立的目录目录下会有一个随机字符串命名的子目录需要将下载的zip文件直接放入这个随机字符串目录中不要解压Android Studio检测到文件存在后会自动继续安装过程提示如果不知道具体缓存路径可以在Android Studio的报错信息中找到类似Could not install Gradle distribution from https://services.gradle.org/distributions/gradle-8.4-bin.zip的提示其中的URL就包含了版本信息。5. 网络代理配置方案5.1 正确配置代理如果你在使用代理网络需要确保Android Studio正确配置了代理打开Android Studio设置File Settings进入Appearance Behavior System Settings HTTP Proxy选择Manual proxy configuration填写正确的代理服务器地址和端口如果需要认证填写用户名和密码点击Check connection测试是否能够访问gradle.org5.2 代理配置注意事项确保代理服务器本身能够访问Gradle官方服务器某些公司网络可能有额外的安全限制需要联系IT部门代理设置更改后需要重启Android Studio才能生效可以尝试在浏览器中直接访问Gradle下载URL测试代理是否有效6. 清理缓存与重新下载6.1 清理Gradle缓存步骤有时候问题可能是由于本地缓存损坏引起的关闭Android Studio删除Gradle缓存目录Windows:C:\Users\你的用户名\.gradle\wrapper\dists\macOS/Linux:~/.gradle/wrapper/dists/重新打开Android Studio并尝试同步项目6.2 缓存清理注意事项清理缓存会导致所有Gradle版本需要重新下载请确保网络畅通大型项目可能会有多个Gradle版本依赖清理后首次同步可能需要较长时间可以只删除特定版本的缓存目录而不是整个dists文件夹7. 其他实用技巧7.1 查看Gradle下载进度在Android Studio的Gradle同步过程中可以通过以下方式查看详细进度打开Gradle工具窗口View Tool Windows Gradle点击右上角的Toggle Gradle offline mode确保离线模式未启用在Build输出控制台中查看详细下载日志7.2 离线模式使用技巧如果网络环境极其不稳定可以考虑使用离线模式下载好所有需要的Gradle版本在Android Studio中启用离线模式File Settings Build, Execution, Deployment Gradle Offline work注意离线模式下无法下载任何新的依赖需要确保所有依赖都已缓存7.3 项目级Gradle配置对于团队项目可以在项目根目录的build.gradle文件中添加国内镜像仓库加速依赖下载buildscript { 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() } }8. 常见问题排查8.1 同步成功后依然报错如果按照上述步骤操作后依然报错可以尝试检查gradle-wrapper.properties文件是否保存检查Android Studio的Gradle设置File Settings Build, Execution, Deployment Gradle确保使用的Gradle版本与项目兼容8.2 版本不兼容问题Gradle版本与Android Gradle插件版本需要匹配查看项目根目录build.gradle中的AGP版本dependencies { classpath com.android.tools.build:gradle:7.4.2 }参考官方兼容性表格选择正确的Gradle版本https://developer.android.com/studio/releases/gradle-plugin#updating-gradle8.3 文件权限问题在Linux/macOS系统下可能会遇到文件权限问题确保当前用户对Gradle缓存目录有读写权限如果之前使用过sudo运行Android Studio可能会导致缓存目录权限混乱9. 高级配置技巧9.1 自定义Gradle安装目录如果你希望将Gradle安装到特定目录可以配置GRADLE_USER_HOME环境变量Windows:右键此电脑 属性 高级系统设置 环境变量新建系统变量GRADLE_USER_HOME值为你希望的路径如D:\gradlemacOS/Linux:编辑~/.bash_profile或~/.zshrc添加export GRADLE_USER_HOME/path/to/your/gradle执行source ~/.bash_profile使更改生效9.2 使用本地Gradle分发对于企业开发环境可以设置内部Gradle分发服务器在内部服务器上托管Gradle发行包修改gradle-wrapper.properties中的distributionUrl指向内部地址这种方式特别适合有严格网络限制的企业环境10. 问题根源分析理解这个问题的根源有助于更好地解决和预防类似问题Gradle的发行包下载机制Android Studio依赖gradle-wrapper.properties文件中指定的URL下载Gradle下载过程使用的是标准的HTTP/HTTPS协议任何网络问题都可能导致下载失败连接重置(SocketException: Connection reset)的常见原因网络中断或不稳定服务器主动断开连接防火墙或安全软件干预代理服务器配置错误Android Studio的处理逻辑首次会尝试从指定URL下载如果失败会抛出异常并显示错误信息不会自动重试或回退到其他镜像11. 预防措施为了避免将来再次遇到这个问题可以采取以下预防措施在项目模板中预先配置国内镜像源在企业内部搭建Gradle镜像服务器将常用的Gradle版本预先下载并放入缓存目录定期维护gradle-wrapper.properties文件中的版本号12. 性能优化建议除了解决连接问题外还可以优化Gradle的整体性能启用Gradle守护进程在gradle.properties中添加org.gradle.daemontrue配置并行构建在gradle.properties中添加org.gradle.paralleltrue增加堆内存在gradle.properties中添加org.gradle.jvmargs-Xmx4096m13. 疑难问题解决记录在实际开发中我还遇到过一些特殊情况和解决方案案例1公司网络特殊限制现象即使配置了代理仍然无法下载解决方案联系IT部门获取特殊白名单权限案例2磁盘空间不足现象下载过程中报错但错误信息不明显解决方案清理磁盘空间后重试案例3Gradle版本号错误现象配置的版本号不存在解决方案核对官方发布页面使用正确的版本号14. 工具与资源推荐Gradle版本查询工具https://gradle.org/releases/国内镜像源阿里云https://mirrors.aliyun.com/gradle/腾讯云https://mirrors.cloud.tencent.com/gradle/网络调试工具curl/wget测试下载链接是否可用telnet测试端口连通性15. 总结与最佳实践经过多次实践我认为处理Gradle下载问题的最佳流程是首先尝试修改gradle-wrapper.properties使用国内镜像如果镜像不可用尝试手动下载并放入缓存目录检查网络代理设置是否正确清理缓存并重新下载如果问题依旧检查更底层的网络问题对于团队开发建议统一使用国内镜像源配置在项目文档中明确Gradle版本要求为新成员提供预配置的开发环境 
长河君 · 2026/10/26 6:27:05 · 阅读 1.2k 解决Android Studio中Gradle下载失败的4种方法
1. 问题现象与背景分析最近在Android Studio中创建新项目时不少开发者遇到了Could not install Gradle distribution from... Connection reset的错误提示。这个报错通常发生在首次创建项目或更新Gradle版本时控制台会显示类似如下的错误信息Could not install Gradle distribution from https://services.gradle.org/distributions/gradle-8.4-bin.zip. Connection reset java.net.SocketException: Connection reset这个问题的本质是Android Studio无法从Gradle官方服务器下载所需的Gradle发行包。在国内开发环境下这个问题尤为常见主要原因包括网络连接问题Gradle官方服务器位于海外国内直接访问可能会遇到网络不稳定或被重置的情况代理配置不当如果开发者使用代理网络但未正确配置Android Studio的代理设置本地Gradle缓存损坏之前下载的Gradle包不完整或损坏防火墙/安全软件拦截某些安全软件可能会阻止Gradle的下载请求2. 解决方案总览针对这个问题我总结了几种有效的解决方法开发者可以根据自己的网络环境和项目需求选择最适合的方案使用国内镜像源替换Gradle官方下载地址推荐手动下载Gradle发行包并配置本地路径检查并正确配置网络代理清理Gradle缓存并重新下载下面我将详细介绍每种解决方案的具体实施步骤和注意事项。3. 使用国内镜像源解决方案3.1 修改gradle-wrapper.properties文件这是最推荐且一劳永逸的解决方案。Gradle的下载地址配置在项目目录下的gradle/wrapper/gradle-wrapper.properties文件中打开你的Android Studio项目在项目面板中找到gradle/wrapper/gradle-wrapper.properties文件修改distributionUrl属性将官方地址替换为国内镜像地址原内容通常类似distributionUrlhttps\://services.gradle.org/distributions/gradle-8.4-bin.zip修改为阿里云镜像distributionUrlhttps\://mirrors.aliyun.com/gradle/gradle-8.4-bin.zip或者腾讯云镜像distributionUrlhttps\://mirrors.cloud.tencent.com/gradle/gradle-8.4-bin.zip3.2 注意事项确保gradle版本号与实际需要的版本一致修改后需要同步Gradle点击Android Studio右上角的Sync Now如果项目中有多个模块确保所有模块的gradle-wrapper.properties文件都进行了修改国内镜像可能会有轻微延迟建议选择离自己地理位置较近的镜像源4. 手动下载Gradle发行包方案4.1 手动下载步骤如果镜像源方案不适用可以尝试手动下载访问Gradle官方发布页面https://gradle.org/releases/找到与项目所需的完全相同的版本注意-bin.zip和-all.zip的区别下载对应的zip文件将下载的文件放入Gradle缓存目录Windows:C:\Users\你的用户名\.gradle\wrapper\dists\gradle-x.x-bin\随机字符串\macOS/Linux:~/.gradle/wrapper/dists/gradle-x.x-bin/随机字符串/4.2 目录结构说明Gradle的缓存目录结构需要注意每个版本对应一个独立的目录目录下会有一个随机字符串命名的子目录需要将下载的zip文件直接放入这个随机字符串目录中不要解压Android Studio检测到文件存在后会自动继续安装过程提示如果不知道具体缓存路径可以在Android Studio的报错信息中找到类似Could not install Gradle distribution from https://services.gradle.org/distributions/gradle-8.4-bin.zip的提示其中的URL就包含了版本信息。5. 网络代理配置方案5.1 正确配置代理如果你在使用代理网络需要确保Android Studio正确配置了代理打开Android Studio设置File Settings进入Appearance Behavior System Settings HTTP Proxy选择Manual proxy configuration填写正确的代理服务器地址和端口如果需要认证填写用户名和密码点击Check connection测试是否能够访问gradle.org5.2 代理配置注意事项确保代理服务器本身能够访问Gradle官方服务器某些公司网络可能有额外的安全限制需要联系IT部门代理设置更改后需要重启Android Studio才能生效可以尝试在浏览器中直接访问Gradle下载URL测试代理是否有效6. 清理缓存与重新下载6.1 清理Gradle缓存步骤有时候问题可能是由于本地缓存损坏引起的关闭Android Studio删除Gradle缓存目录Windows:C:\Users\你的用户名\.gradle\wrapper\dists\macOS/Linux:~/.gradle/wrapper/dists/重新打开Android Studio并尝试同步项目6.2 缓存清理注意事项清理缓存会导致所有Gradle版本需要重新下载请确保网络畅通大型项目可能会有多个Gradle版本依赖清理后首次同步可能需要较长时间可以只删除特定版本的缓存目录而不是整个dists文件夹7. 其他实用技巧7.1 查看Gradle下载进度在Android Studio的Gradle同步过程中可以通过以下方式查看详细进度打开Gradle工具窗口View Tool Windows Gradle点击右上角的Toggle Gradle offline mode确保离线模式未启用在Build输出控制台中查看详细下载日志7.2 离线模式使用技巧如果网络环境极其不稳定可以考虑使用离线模式下载好所有需要的Gradle版本在Android Studio中启用离线模式File Settings Build, Execution, Deployment Gradle Offline work注意离线模式下无法下载任何新的依赖需要确保所有依赖都已缓存7.3 项目级Gradle配置对于团队项目可以在项目根目录的build.gradle文件中添加国内镜像仓库加速依赖下载buildscript { 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() } }8. 常见问题排查8.1 同步成功后依然报错如果按照上述步骤操作后依然报错可以尝试检查gradle-wrapper.properties文件是否保存检查Android Studio的Gradle设置File Settings Build, Execution, Deployment Gradle确保使用的Gradle版本与项目兼容8.2 版本不兼容问题Gradle版本与Android Gradle插件版本需要匹配查看项目根目录build.gradle中的AGP版本dependencies { classpath com.android.tools.build:gradle:7.4.2 }参考官方兼容性表格选择正确的Gradle版本https://developer.android.com/studio/releases/gradle-plugin#updating-gradle8.3 文件权限问题在Linux/macOS系统下可能会遇到文件权限问题确保当前用户对Gradle缓存目录有读写权限如果之前使用过sudo运行Android Studio可能会导致缓存目录权限混乱9. 高级配置技巧9.1 自定义Gradle安装目录如果你希望将Gradle安装到特定目录可以配置GRADLE_USER_HOME环境变量Windows:右键此电脑 属性 高级系统设置 环境变量新建系统变量GRADLE_USER_HOME值为你希望的路径如D:\gradlemacOS/Linux:编辑~/.bash_profile或~/.zshrc添加export GRADLE_USER_HOME/path/to/your/gradle执行source ~/.bash_profile使更改生效9.2 使用本地Gradle分发对于企业开发环境可以设置内部Gradle分发服务器在内部服务器上托管Gradle发行包修改gradle-wrapper.properties中的distributionUrl指向内部地址这种方式特别适合有严格网络限制的企业环境10. 问题根源分析理解这个问题的根源有助于更好地解决和预防类似问题Gradle的发行包下载机制Android Studio依赖gradle-wrapper.properties文件中指定的URL下载Gradle下载过程使用的是标准的HTTP/HTTPS协议任何网络问题都可能导致下载失败连接重置(SocketException: Connection reset)的常见原因网络中断或不稳定服务器主动断开连接防火墙或安全软件干预代理服务器配置错误Android Studio的处理逻辑首次会尝试从指定URL下载如果失败会抛出异常并显示错误信息不会自动重试或回退到其他镜像11. 预防措施为了避免将来再次遇到这个问题可以采取以下预防措施在项目模板中预先配置国内镜像源在企业内部搭建Gradle镜像服务器将常用的Gradle版本预先下载并放入缓存目录定期维护gradle-wrapper.properties文件中的版本号12. 性能优化建议除了解决连接问题外还可以优化Gradle的整体性能启用Gradle守护进程在gradle.properties中添加org.gradle.daemontrue配置并行构建在gradle.properties中添加org.gradle.paralleltrue增加堆内存在gradle.properties中添加org.gradle.jvmargs-Xmx4096m13. 疑难问题解决记录在实际开发中我还遇到过一些特殊情况和解决方案案例1公司网络特殊限制现象即使配置了代理仍然无法下载解决方案联系IT部门获取特殊白名单权限案例2磁盘空间不足现象下载过程中报错但错误信息不明显解决方案清理磁盘空间后重试案例3Gradle版本号错误现象配置的版本号不存在解决方案核对官方发布页面使用正确的版本号14. 工具与资源推荐Gradle版本查询工具https://gradle.org/releases/国内镜像源阿里云https://mirrors.aliyun.com/gradle/腾讯云https://mirrors.cloud.tencent.com/gradle/网络调试工具curl/wget测试下载链接是否可用telnet测试端口连通性15. 总结与最佳实践经过多次实践我认为处理Gradle下载问题的最佳流程是首先尝试修改gradle-wrapper.properties使用国内镜像如果镜像不可用尝试手动下载并放入缓存目录检查网络代理设置是否正确清理缓存并重新下载如果问题依旧检查更底层的网络问题对于团队开发建议统一使用国内镜像源配置在项目文档中明确Gradle版本要求为新成员提供预配置的开发环境