Gradle代理必须显式配置在~/.gradle/gradle.properties中，分别设置HTTP/HTTPS代理地址与端口，认证需追加用户名密码；HTTPS中间人代理需导入根CA证书至JVM信任库，并配合阿里云等镜像源提升稳定性。
Gradle 本身不自动继承系统代理或浏览器设置，必须显式配置才能在复杂网络环境（如企业内网、防火墙拦截、HTTPS 中间人代理等）下正常拉取远程依赖。关键在于区分“Gradle 进程的网络行为”和“构建中 Java 应用的运行时行为”，这里聚焦前者——即 Gradle 在执行 ./gradlew build、解析仓库、下载 JAR/POM 时的代理控制。
Gradle 自身代理必须写在 gradle.properties 中
Gradle 启动时会优先读取用户级 ~/.gradle/gradle.properties（Windows 是 %USERPROFILE%\.gradle\gradle.properties），这是最稳定、项目无关的配置方式。不要依赖命令行临时加参数（易遗漏、难复用），也不要指望环境变量 http_proxy 自动生效（Gradle 默认不读取）。
systemProp.http.proxyHost=127.0.0.1systemProp.http.proxyPort=7890systemProp.https.proxyHost=127.0.0.1systemProp.https.proxyPort=7890-
systemProp.http.nonProxyHosts=localhost|127.0.0.1|*.corp.local（竖线分隔，*仅支持前缀通配）
注意：HTTP 和 HTTPS 代理必须**分别指定**，即使指向同一台代理服务（如 Clash、Charles、公司网关）。只配 HTTP 代理时，Maven Central 或 JCenter 的 HTTPS 请求仍会直连失败。
代理需认证时的处理要点
若代理要求用户名密码，继续追加：
立即学习“Java免费学习笔记（深入）”；
systemProp.http.proxyUser=your-usernamesystemProp.http.proxyPassword=your-passsystemProp.https.proxyUser=your-usernamesystemProp.https.proxyPassword=your-pass
⚠️ 明文密码有安全风险。生产环境建议改用 NTLM 认证代理（需额外 JVM 参数或切换到支持它的代理客户端），或通过本地 socks 代理中转（如 systemProp socksProxyHost）避免暴露凭证。
HTTPS 代理拦截导致 PKIX 错误怎么办
企业常用中间人代理（如 Zscaler、Blue Coat）会替换 TLS 证书，Gradle 下载时校验失败，报 PKIX path building failed。此时光配代理参数没用，必须把代理的根 CA 证书导入 JVM 的信任库：
- 找到 Gradle 使用的 JDK（可通过
org.gradle.java.home在gradle.properties中指定） - 执行：
$JAVA_HOME/bin/keytool -importcert -alias proxy-ca -file proxy-root.crt -keystore $JAVA_HOME/jre/lib/security/cacerts - 默认口令是
changeit，导入后重启 Gradle daemon（./gradlew --stop）
跳过证书校验（-Djavax.net.ssl.trustAll=true）仅限调试，严禁用于 CI 或生产。
配合镜像仓库进一步提升稳定性
单纯靠代理可能仍慢或不稳定。推荐在 build.gradle 中将默认仓库替换为国内镜像，例如：
repositories {
maven { url 'https://maven.aliyun.com/repository/public' }
maven { url 'https://maven.aliyun.com/repository/google' }
mavenCentral()
}
或者用 ~/.gradle/init.gradle 全局重定向所有项目：
allprojects {
repositories {
def ALIYUN_REPO = 'https://maven.aliyun.com/repository/public'
if (repositories.find { it.url.toString().contains('mavenCentral') }) {
repositories.mavenCentral { content { includeGroup 'com.*' } }
repositories.remove(repositories.mavenCentral)
repositories.maven { url ALIYUN_REPO }
}
}
}
这样即使代理偶尔抖动，高频依赖也能从镜像快速命中。
