Android Studio Gradle 下载慢、超时与国内镜像配置

一、 问题现象与常见错误信息

在 Windows 上首次安装 Android Studio 并新建项目时，约 70% 的初学者都会遭遇如下典型故障：

• 进度条长久停滞：底部状态栏一直显示 Downloading https://services.gradle.org/distributions/gradle-x.x-bin.zip，持续数十分钟不动或频繁卡在 99%。
• 网络连接超时报错：

  Connect to services.gradle.org:443 [services.gradle.org/...] failed: Connection timed out
  或
  java.net.SocketTimeoutException: Read timed out

• 依赖同步失败：提示 Could not resolve com.android.tools.build:gradle:8.x.x，无法从 dl.google.com 或 repo.maven.apache.org 拉取插件。

二、 为什么 Gradle 下载会如此缓慢？

要彻底解决问题，首先需理清 Gradle 构建分为两层不同的网络拉取：

1. 第一层：Gradle Wrapper 运行时分发包 (`gradle-x.x-bin.zip`)：这是 Gradle 自身的二进制执行程序（通常在 150MB~200MB）。官方地址托管在 services.gradle.org，由于国内无直接 CDN 边缘节点，直连经常被限速或握手超时。
2. 第二层：工程第三方依赖与 Android Gradle 插件 (AGP)：Gradle 启动后，需要从 Google Maven (dl.google.com/dl/android/maven2/) 和 Maven Central 下载各种 jar/aar 依赖，国内开发者直连往往速度极慢。

三、 手动解决方法

方法 1：替换 Gradle Wrapper 为国内镜像下载地址

在你的 Android 项目根目录中，打开文件：gradle/wrapper/gradle-wrapper.properties，将默认的官方地址替换为国内腾讯云镜像：

# 原官方地址 (慢):
# distributionUrl=https\://services.gradle.org/distributions/gradle-8.9-bin.zip

# 替换为腾讯云镜像源 (极速):
distributionUrl=https\://mirrors.cloud.tencent.com/gradle/gradle-8.9-bin.zip

修改保存后，点击 Android Studio 右上角的 Sync Project with Gradle Files（小象图标）重新触发下载。

方法 2：全局配置阿里云/腾讯云 Maven 镜像

为了让后续所有项目无需重复修改即可满速下载依赖，可以在用户主目录下新建或修改全局 Init 脚本。路径为：C:\Users\你的用户名\.gradle\init.gradle（如果使用 AutoAS，则位于统一配置的独立目录下）：

allprojects {
    repositories {
        maven { url 'https://maven.aliyun.com/repository/google' }
        maven { url 'https://maven.aliyun.com/repository/public' }
        maven { url 'https://maven.aliyun.com/repository/gradle-plugin' }
        mavenCentral()
        google()
    }
}

方法 3：手动下载离线 Zip 包并放置到缓存路径

如果你已经从国内镜像或他人处下载好了 gradle-8.9-bin.zip，切勿直接解压，而是放置在系统对应的哈希文件夹中：

路径一般位于：C:\Users\你的用户名\.gradle\wrapper\dists\gradle-8.9-bin\[随机哈希串]\。将 zip 文件直接放入该文件夹内，重启 Android Studio，系统将自动识别解压。

---