Android Studio Gradle 同步/下载失败完整解决方案

核心原因：国内网络访问国外gradle分发服务器、google maven仓库超时。分两步：修改gradle-wrapper（下载gradle本体） + 修改settings.gradle（下载项目依赖）

1. 修改 gradle-wrapper.properties（解决 Could not install Gradle distribution）

文件路径：项目目录/gradle/wrapper/gradle-wrapper.properties
找到 distributionUrl，把官方地址替换成腾讯镜像：

# 修改前
#distributionUrl=https\://services.gradle.org/distributions/gradle-9.7.1-bin.zip

# 修改后（版本号保持和原来一致，只替换域名）
distributionUrl=https\://mirrors.cloud.tencent.com/gradle/gradle-9.7.1-bin.zip

镜像地址：[https://mirrors.cloud.tencent.com/gradle/](https://mirrors.cloud.tencent.com/gradle/)，找到对应版本bin包

手动离线方案（镜像也下不动时）

1. 浏览器去腾讯镜像下载对应版本 gradle-x.x-bin.zip
2. File → Settings → Build, Execution, Deployment → Build Tools → Gradle，复制 Gradle user home
3. 进入 .gradle/wrapper/dists/gradle-xxx-bin/一串随机哈希文件夹，把zip丢进去，不要解压
4. 重新同步

2. 修改 settings.gradle（新版AS，依赖仓库镜像，最重要）

Android Studio Hedgehog / Iguana / Jellyfish 及以后，仓库配置在 settings.gradle，不是根build.gradle

pluginManagement {
    repositories {
        // 国内镜像放最前面，优先使用
        maven { url '[https://maven.aliyun.com/repository/google](https://maven.aliyun.com/repository/google)' }
        maven { url '[https://maven.aliyun.com/repository/public](https://maven.aliyun.com/repository/public)' }
        maven { url '[https://maven.aliyun.com/repository/gradle-plugin](https://maven.aliyun.com/repository/gradle-plugin)' }
        google()
        mavenCentral()
        gradlePluginPortal()
    }
}
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        maven { url '[https://maven.aliyun.com/repository/google](https://maven.aliyun.com/repository/google)' }
        maven { url '[https://maven.aliyun.com/repository/public](https://maven.aliyun.com/repository/public)' }
        google()
        mavenCentral()
    }
}
rootProject.name = "MyApp"
include ':app'

旧项目（老gradle）则修改根目录 build.gradle 的 buildscript 和 allprojects 的 repositories。

3. 修改 gradle.properties（增加超时、全局代理开关）

项目根目录 gradle.properties，添加：

# 延长超时时间
org.gradle.internal.http.connectionTimeout=60000
org.gradle.internal.http.socketTimeout=60000

# 如果不需要代理，关闭（很多人因为系统代理导致同步失败）
systemProp.http.proxyHost=
systemProp.http.proxyPort=
systemProp.https.proxyHost=
systemProp.https.proxyPort=

4. 清理缓存（配置完镜像依然报错时）

1. 菜单：File → Invalidate Caches... → 勾选 Clear file system cache and local history，Invalidate and Restart
2. 关闭Android Studio
3. 删除项目下 .idea、.gradle、app/build 文件夹
4. 删除用户目录下 .gradle/caches（缓存损坏经常导致同步失败）
5. 重新打开项目，点击 Sync Now

5. 版本兼容检查（报错：AGP和Gradle版本不匹配）

Android Gradle Plugin(AGP)版本（在build.gradle里）必须和gradle-wrapper里的gradle版本对应，版本不匹配直接同步失败。
例：AGP 8.1 → Gradle 8.1，不能混用。

6. 常见坑排查

1. 代理问题：电脑开了***/VPN，AS自动拾取代理；关掉系统代理，或者在AS设置里手动取消HTTP proxy
2. 中文路径：项目路径不要有中文、空格、特殊字符，会导致各种诡异同步失败
3. 防火墙/杀毒软件：拦截网络请求，临时关闭测试
4. JDK版本：新版AS自带JDK，不要自己乱改项目JDK

7. 一键验证顺序（推荐按顺序试）

1. 修改 gradle-wrapper.properties → 替换gradle下载地址
2. 修改 settings.gradle 添加阿里云maven镜像
3. Invalidate Caches重启
4. 仍失败：手动下载gradle zip放到gradle缓存目录
5. 检查AGP/Gradle版本兼容性