Android Studio 与 Gradle 编译过程中网络超时的代理排错

任何从事过 Android 原生开发的程序员，都体验过首次导入项目时 Syncing... 几个小时然后爆出 Read time out 的绝望。由于 Google 服务及一些核心 Maven 仓库的特殊性，为 Android Studio 与底层的 Gradle 引擎打通代理任督二脉至关重要。

1. 错位的代理配置层次

Android Studio 面临的网络问题复杂程度远超前端。它分为两个完全独立的层级：

• IDE 层面：你在 Android Studio 设置面板里配置的 HTTP Proxy，仅仅对 IDE 本身生效（用于下载 SDK 更新、插件更新）。
• 构建层 (Gradle)：在后台疯狂拉取数十兆依赖包的是 Gradle 守护进程，它完全不理会 IDE 界面的代理配置（除非你在弹出的提示框中明确点击了“同步给 Gradle”），这也是最容易踩坑的地方。

2. 深入排错：揪出幽灵配置文件

即使你清空了环境变量，某天编译突然依然报代理连接错误，往往是因为缓存文件作祟。

1. 全局级拦截：请立即检查当前电脑用户目录下的 ~/.gradle/gradle.properties。如果历史开发中在此写入过诸如 systemProp.http.proxyHost=127.0.0.1 且后来你的本地代理端口已经更换（比如从 1080 变为了 10809），该死锁会一直伴随所有的项目编译。
2. 项目级拦截：检查当前安卓项目根目录下的 gradle.properties，确保其没有携带错误的代理覆盖配置。

3. 正确的注入策略

推荐在 ~/.gradle/gradle.properties 中静态写死当前正在运行的代理客户端如 Clash 或 v2rayN 端口：

systemProp.http.proxyHost=127.0.0.1
systemProp.http.proxyPort=10809
systemProp.https.proxyHost=127.0.0.1
systemProp.https.proxyPort=10809

安全警告：如果项目是公司的内网隔离项目，绝不允许将带有外网代理配置的 gradle.properties 提交入 Git 仓库，否则会在内网 CI/CD 流水线上造成灾难性的构建中断。

---

参考资料与相关阅读

• Android Studio 官方文档 - 配置构建代理
• 相关阅读：CI/CD 流水线中构建环境的代理安全隔离