← 返回博客

如何在Android Studio和Gradle中设置代理:gradle.properties和SDK管理器

我们将讨论如何正确在gradle.properties中设置代理,配置SDK管理器和Android Studio,以及解决Gradle同步中最常见的错误。

📅2026年11月13日

如果 Android Studio 在 Gradle 同步阶段“卡住”,SDK 管理器无法加载组件,而 Maven Central 的依赖项无法下载——在 80% 的情况下,问题不在代码,而在网络环境。企业防火墙、VPN、IP 仓库的封锁或直接缺乏互联网访问——所有这些都可以通过在三个层次上正确设置代理来解决:IDE、Gradle 和 SDK 管理器。我们将讨论如何正确设置代理,避免不必要的同步错误。

为什么 Android 开发者需要代理

通常情况下,代理与 Android Studio 一起使用有几种场景。第一个场景是企业网络,直接访问互联网被关闭,所有流量,包括对 google()、mavenCentral() 和 dl.google.com 的请求,必须通过公司的代理服务器。第二个场景是绕过地区限制:某些 SDK 组件、Google Play 服务 API 或第三方仓库在某些国家无法直接访问,开发者不得不通过其他地理位置的 IP 路由流量。

第三个场景是测试应用程序的地理依赖功能。如果应用程序根据用户所在国家显示不同的内容、价格或广告,QA 工程师和开发者需要在构建和调试阶段模拟来自特定地区的请求,而不必等到发布。第四个场景是与 CI/CD 运行器合作,这些运行器物理上位于对某些服务访问有限的数据中心,代理成为“联系”所需仓库或 API 的唯一方式。

在所有这些情况下,逻辑是相同的:Gradle、SDK 管理器和 IDE 本身必须知道代理服务器的地址、端口,以及必要时的凭据,否则项目同步将因超时或连接错误而失败。

选择哪种类型的代理进行开发

对于开发和测试而言,重要的不是匿名性,而是连接的稳定性和在长时间下载期间的低中断率(例如,Android SDK 平台工具的大小达到数百兆字节)。下面是针对 Android 开发者任务的代理类型比较。

代理类型 何时使用 特点
数据中心代理 下载 SDK,同步 Gradle,CI/CD 高速,低成本,适合大文件下载
住宅代理 测试地理依赖的 API 和内容 真实用户的 IP,较少被服务阻止
移动代理 从特定国家测试移动 API 和推送通知 运营商的 IP,尽可能接近真实的移动流量

为了实现纯粹的 Gradle 同步和下载依赖项,最好使用 数据中心代理——它们提供稳定的高速,无额外延迟。如果任务是检查应用程序的后端如何响应来自其他国家的用户,住宅或移动 IP 更为合适。

在 gradle.properties 中设置代理

gradle.properties 文件是 Gradle 查找 HTTP 和 HTTPS 连接代理设置的主要位置。该文件可以位于项目根目录(仅对该项目有效)或全局目录 ~/.gradle/gradle.properties(对机器上的所有项目有效)。为了通过代理持续工作,建议使用第二种方式。

# ~/.gradle/gradle.properties

systemProp.http.proxyHost=proxy.example.com
systemProp.http.proxyPort=8080
systemProp.https.proxyHost=proxy.example.com
systemProp.https.proxyPort=8080

# 可选——直接访问的例外,不通过代理
systemProp.http.nonProxyHosts=localhost|127.0.0.1|*.internal.corp

保存文件后,请务必点击 File → Sync Project with Gradle Files 或工具栏上的“象”图标。如果 IDE 没有自动检测到更改,请重新启动 Android Studio——有时代理设置的缓存会在 Gradle Daemon 进程重启之前保持不变。

重要提示:systemProp.* 参数仅在执行 Gradle 的 JVM 层面上有效,因此它们不仅影响依赖项的下载,还影响构建脚本内部的任何网络请求(例如,如果您有自定义的 Gradle 任务,它调用外部 API)。

在 Android Studio 中设置代理

除了 Gradle,IDE 还有自己的网络设置——这些设置用于插件、IDE 更新、许可证检查以及一些功能,如来自 Google 的提示。可以通过 File → Settings → Appearance & Behavior → System Settings → HTTP Proxy 打开它们(在 macOS 上为 Android Studio → Preferences)。

在打开的窗口中,选择 Manual proxy configuration,指定主机和端口,如有必要,勾选 Proxy authentication 并输入用户名和密码。那里还有一个方便的 Check connection 按钮——输入测试 URL(例如,https://dl.google.com)并点击它,以确保连接正常,然后再进行完整的项目同步。

重要的是要理解区别

设置中的 HTTP Proxy 设置影响 IDE 本身(插件、更新),而 gradle.properties 中的参数影响 Gradle 构建过程。这是两个独立的机制,通常需要同时设置两个才能在代理后正常工作。

SDK 管理器的代理

SDK 管理器是一个独立的组件,用于下载 Android 平台、构建工具、模拟器和系统映像。它有自己的代理配置,历史上通过 IDE 的相同系统设置进行设置,但在通过独立的 sdkmanager(命令行工具)工作时,参数需要通过 JVM 标志显式传递。

sdkmanager --proxy=http \
  --proxy_host=proxy.example.com \
  --proxy_port=8080 \
  --list

如果 sdkmanager 通过脚本启动,可以直接在 JAVA_OPTS 环境变量中设置代理,该变量由可执行文件读取:

export JAVA_OPTS="-Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080 \
-Dhttps.proxyHost=proxy.example.com -Dhttps.proxyPort=8080"

常见错误是设置 Android Studio 中的代理,但忘记了独立工具,如 sdkmanager 或 avdmanager,它们在单独的 Java 进程中运行,并不会自动继承 IDE 的设置。

gradlew 的代理和环境变量

如果您通过 ./gradlew 从终端构建项目,绕过 IDE(例如,在 CI/CD 中或仅仅出于习惯),可以直接在命令中传递代理,而无需更改 gradle.properties:

./gradlew build \
  -Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080 \
  -Dhttps.proxyHost=proxy.example.com -Dhttps.proxyPort=8080

为了方便长期使用,可以在 shell 配置文件中设置环境变量 GRADLE_OPTS(Linux/macOS 的 .bashrc、.zshrc 或 Windows 的环境变量):

export GRADLE_OPTS="-Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080 -Dhttps.proxyHost=proxy.example.com -Dhttps.proxyPort=8080"

这在 GitHub Actions、GitLab CI 或 Jenkins 的 CI 运行器中尤其有用,其中环境变量在作业级别设置一次,随后构建的所有步骤都会自动获取,而无需编辑项目文件。

常见的同步错误及其解决方案

我们将讨论开发者在设置代理时遇到的最常见错误及其具体解决步骤。

错误 原因 解决方案
连接超时 未指定代理或代理不可用 检查 gradle.properties 中的主机/端口,通过 curl 测试代理的可用性
407 代理认证要求 未提供用户名/密码 添加 systemProp.http.proxyUser 和 systemProp.http.proxyPassword
无法解析主机 DNS 解析未通过代理进行 使用 socksProxyHost 替代 http 进行远程 DNS 的 SOCKS5
无法获取 'https://dl.google.com/...' Gradle 设置已指定,但在 IDE 中未设置(或反之亦然) 在两个地方同步设置:Settings → HTTP Proxy 和 gradle.properties
SSL 握手失败 代理拦截 SSL(企业 MITM) 将代理的根证书导入到您的 JDK 的 cacerts 中

如果错误在下载特定的 Maven 工件(例如,androidx.* 库)时发生,临时启用 Gradle 的详细日志,通过命令 ./gradlew build --info——输出中将显示连接中断的具体请求以及服务器返回的响应代码。

需要认证的代理:用户名和密码

如果代理需要身份验证(这是付费代理服务和企业网关的标准情况),需要在 gradle.properties 中添加另外两行:

systemProp.http.proxyUser=myuser
systemProp.http.proxyPassword=mypassword
systemProp.https.proxyUser=myuser
systemProp.https.proxyPassword=mypassword

将代理密码以明文形式存储在项目的 gradle.properties 中,该文件会被纳入版本控制——这是一种不好的做法。请使用用户主目录中的全局文件,该文件不会被提交到 Git,或者在 CI/CD 阶段通过环境变量传递密码,以确保秘密不会泄露到代码库中。

对于需要 IP 轮换的场景(例如,从不同地址测试 API 限制),使用具有现成地址池和统一登录的代理服务更为方便——这样,轮换在提供商一侧设置,而在 gradle.properties 中只需更改会话端口,无需重写整个项目的配置。

诊断检查清单

如果在所有设置后同步仍然失败,请按顺序检查以下项目:

  • 通过命令 curl -x http://proxy.example.com:8080 https://dl.google.com 检查代理的可用性
  • 确保在 Settings → HTTP Proxy 和 gradle.properties 中同时设置了代理
  • 清除 Gradle 缓存:./gradlew --stop 并删除文件夹 .gradle/caches
  • 检查文件中是否存在多余的空格和引号围绕主机/端口的值
  • 如果使用 SOCKS5——请使用 socksProxyHost/socksProxyPort 替代 http.proxyHost
  • 对于企业 MITM 代理,将证书导入 JDK 的受信任证书存储中(keytool -import)
  • 在 properties 文件发生任何更改后,重新启动 Android Studio 和 Gradle Daemon

结论

在 Android 开发中设置代理是三个层次的工作:Android Studio 的系统设置用于 IDE 本身,gradle.properties 中的 systemProp 参数用于构建过程,以及独立工具如 sdkmanager 的单独配置。大多数同步错误正是由于其中一个层次已设置,而另一个被遗忘,或者由于缺乏对需要身份验证的代理的授权。

如果任务只是通过工作代理稳定地下载依赖项和 SDK 组件,数据中心代理 非常适合——它们快速且在大文件下载时不会造成额外延迟。如果需要测试应用程序在特定国家或移动运营商下的表现,请考虑使用 住宅代理 或 移动 IP——它们提供了不同地区服务行为的更真实图景。