同步指南

制定日期：2026-06-22 编写背景：解决 zut-stu 校园网环境 + Clash Verge 代理下，Android Studio 同步 Gradle 依赖多次失败（超时、403 Forbidden、SSL peer shut down）的问题。

---

一、遇到的核心问题与根因

在 Android Studio 中同步 Gradle 项目时，遇到了以下三种连续的网络报错：

1. Could not HEAD 'https://repo.maven.apache.org/...' 导致超时

• 表现：Gradle Sync 长时间卡在下载依赖界面，最终连接超时失败。
• 根因：当前处于中原理工学院校园网 zut-stu，该网络对国外 Maven Central 仓库、Google Maven 仓库进行限制或劫持，直连极难成功。

2. Received status code 403 from server: Forbidden

• 表现：从国外官方仓库下载某些 POM 文件时，直接返回 403 拒绝访问错误。
• 根因：校园网网关劫持了 HTTPS 请求重定向至 Portal 登录页面，或代理节点的 IP 被 Maven Central 官方的安全防护机制（WAF）拦截屏蔽。

3. SSL peer shut down incorrectly

• 表现：Gradle 在下载依赖时报错，SSL 握手被异常重置关闭。
• 根因：Android Studio 的代理设置为了 Auto-detect（自动检测），自动读取了 Clash 代理端口 7897 并强加给 Gradle。然而 Gradle 守护进程（Daemon）在通过该本地环回地址（Loopback Proxy）与 Clash 通信时，可能因为 Windows 的环回限制或节点切换导致握手失败，被防火墙或代理软件重置。

---

二、尝试过的排查过程

为了解决上述问题，我们进行了一系列尝试，并发现了许多 Gradle 与 Android Studio 的隐藏机制：

❌ 尝试 1：修改项目级 build.gradle 并注释官方仓库

• 结果：部分依赖好转，但依然报错。
• 原因：项目使用了 Capacitor 框架，引入了许多存放在 node_modules 里的原生子模块（如 :capacitor-android、:capacitor-keyboard）。这些子模块内部 of build.gradle 仍然硬编码了 google() 和 mavenCentral()，它们依旧会绕过主项目的仓库设置去连接国外官网。

❌ 尝试 2：在项目 android/ 下配置 init.gradle 拦截器

• 结果：完全失效，Android Studio 依然报错。
• 原因：init.gradle（初始化脚本）只有在命令行通过 -I init.gradle 参数手动指定时才会被读取。Android Studio 在运行同步时并不会自动读取项目目录下的初始化脚本。

❌ 尝试 3：修改 gradle.properties 代理后直接重试

• 结果：依然报错。
• 原因：Gradle 是以 Daemon 守护进程 驻留在后台内存的（默认存活 3 小时）。即便修改了配置文件或 IDE 里的代理开关，正在运行的 Daemon 依然在使用旧的缓存代理配置，必须手动执行 .\gradlew --stop 杀死守护进程才能生效。

---

三、最终解决方案（黄金配置）

经过多轮排查，我们沉淀了一套一劳永逸的国内 Gradle 极速同步方案：

1. 建立全局 Gradle 拦截脚本（最核心）

在电脑当前用户的全局 Gradle 目录中创建拦截脚本：

• 文件路径：C:\Users\user\.gradle\init.gradle

• 脚本内容：

  gradle.allprojects { project ->
    project.buildscript.repositories.all { repo ->
        if (repo instanceof MavenArtifactRepository) {
            def url = repo.url.toString()
            if (url.startsWith('https://repo1.maven.org/maven2') || url.startsWith('https://repo.maven.apache.org/maven2') || url.startsWith('http://repo1.maven.org/maven2')) {
                repo.url = 'https://maven.aliyun.com/repository/public'
            } else if (url.startsWith('https://jcenter.bintray.com')) {
                repo.url = 'https://maven.aliyun.com/repository/public'
            } else if (url.startsWith('https://dl.google.com/dl/android/maven2') || url.startsWith('http://dl.google.com/dl/android/maven2')) {
                repo.url = 'https://maven.aliyun.com/repository/google'
            } else if (url.startsWith('https://plugins.gradle.org/m2')) {
                repo.url = 'https://maven.aliyun.com/repository/gradle-plugin'
            }
        }
    }
    project.repositories.all { repo ->
        if (repo instanceof MavenArtifactRepository) {
            def url = repo.url.toString()
            if (url.startsWith('https://repo1.maven.org/maven2') || url.startsWith('https://repo.maven.apache.org/maven2') || url.startsWith('http://repo1.maven.org/maven2')) {
                repo.url = 'https://maven.aliyun.com/repository/public'
            } else if (url.startsWith('https://jcenter.bintray.com')) {
                repo.url = 'https://maven.aliyun.com/repository/public'
            } else if (url.startsWith('https://dl.google.com/dl/android/maven2') || url.startsWith('http://dl.google.com/dl/android/maven2')) {
                repo.url = 'https://maven.aliyun.com/repository/google'
            } else if (url.startsWith('https://plugins.gradle.org/m2')) {
                repo.url = 'https://maven.aliyun.com/repository/gradle-plugin'
            }
        }
    }
  }

  作用：只要这台电脑运行 Gradle，不管是哪个项目，任何插件、依赖、第三方库试图从 Google、Maven Central 或 Gradle 官方插件源下载时，都会被动态拦截并重定向到国内的阿里云镜像源。下载速度可达数十MB/s，且彻底避免 403 和超时问题。

2. 停用局部代理，依靠 TUN 模式

• 打开项目中的 android/gradle.properties。
• 将 systemProp.http.proxyHost 等 4 行代理配置用 # 注释掉。
• 原因：因为您的 Clash Verge 开启了 TUN 网卡全局接管，系统流量本身已透明代理，不需要且不建议在项目内硬编码 127.0.0.1 代理，否则会导致本地环回 SSL 握手异常。

3. 将 Android Studio 代理设为 No proxy

• 进入 File -> Settings -> Appearance & Behavior -> System Settings -> HTTP Proxy。
• 将原本选中的 Auto-detect proxy settings 修改为 No proxy。
• 作用：防止 Android Studio 在启动同步时把系统代理隐式地注入给 Gradle。

4. 杀死运行中的 Daemon 进程以应用新配置

每次修改网络/代理配置后，在终端运行以下命令重置进程：

# 停止当前运行 of Gradle Daemon
.\gradlew.bat --stop

---

四、未来排错 Checklist

如果以后导入新 Android 项目又遇到网络爆红，请按以下步骤快速排查：

1. 检查浏览器能否正常打开国内网页：确保没有欠费或校园网 Portal 未登录。
2. 检查全局拦截脚本是否存在：打开 C:\Users\user\.gradle\init.gradle，确认代码完整无损。
3. 检查 Android Studio 代理：确认 HTTP Proxy 设置为 No proxy。
4. 检查项目 gradle.properties：确认没有硬编码残留的 systemProp.http 代理配置。
5. 强制重置进程：在终端执行 .\gradlew.bat --stop 杀死守护进程，然后重新点击 Try Again。