### [Maven和Gradle怎么配置代理？settings.xml、systemProp与仓库排查](https://www.jiyueip.com/article/7975)

**Published:** 2026-07-22T18:21:41

**Author:** 斑斓助理

**Excerpt:** Maven与Gradle的代理配置文件、非代理主机、守护进程和仓库定义并不相同。本文说明settings.xml、gradle.properties、systemProp、证书信任、凭据保护与验证方法。

Maven或Gradle下载依赖失败时，浏览器能访问中央仓库并不能证明构建进程网络正常。构建工具由JVM启动，读取自己的配置文件，还可能经过企业镜像仓库、插件仓库和重定向域名。排查时要先分清“仓库地址不对”与“到仓库的网络路径不通”。

## 一、先画出构建请求路径

一个常见路径是：构建工具读取项目文件，解析仓库配置，经HTTP代理访问公共或私有仓库，再下载POM、元数据、插件和制品。任一环节都可能返回不同错误。401通常属于仓库认证，407属于代理认证，502或超时则要继续区分代理和上游。

## 二、Maven代理配置放在哪里

Maven通常在用户目录或安装目录的`settings.xml`中读取`<proxies>`。一个代理项包含是否启用、协议、主机、端口，以及可选的账号、密码和`nonProxyHosts`。团队成员应明确使用的是用户级还是全局配置，避免修改了一个文件，实际运行却读取另一个。

```
<proxy>
  <active>true</active>
  <protocol>http</protocol>
  <host>proxy.example</host>
  <port>8080</port>
  <nonProxyHosts>localhost|*.corp.example</nonProxyHosts>
</proxy>
```

示例只展示结构，不应把真实凭据提交到代码仓库。

## 三、Gradle为什么要关注systemProp

Gradle常通过`gradle.properties`设置`systemProp.http.proxyHost`、`systemProp.http.proxyPort`及HTTPS对应属性。配置可能存在于项目目录、用户目录或系统级位置。遇到冲突时，先输出实际执行环境和Gradle版本，再逐个缩小配置来源。

| 对象  | Maven | Gradle |
| --- | --- | --- |
| 常见配置文件 | settings.xml | gradle.properties |
| 代理入口 | proxies节点 | JVM systemProp属性 |
| 后台进程 | 通常单次进程 | 可能复用Gradle Daemon |
| 非代理目标 | nonProxyHosts | http.nonProxyHosts等JVM属性 |

## 四、改完配置后Gradle仍走旧代理

Gradle Daemon会复用JVM进程。配置、环境变量或证书发生变化后，旧Daemon可能继续保留原有状态。可以先执行`gradle --stop`停止对应版本的Daemon，再重新运行最小任务。不要一上来删除所有缓存，缓存与网络配置属于不同问题。

## 五、nonProxyHosts最容易写错什么

JVM体系中的非代理主机语法不能简单等同于通用`NO_PROXY`。常见实现使用竖线分隔，并允许有限通配。应把本地仓库、内网域名和回环地址逐项验证，同时避免把过宽泛的域名加入绕过清单，否则本应受控的外部请求可能直接出网。

Java系统属性和`ProxySelector`的区别，可参考[Java程序代理配置指南](https://www.jiyueip.com/article/7959)。

## 六、仓库配置为什么也会造成“像代理”的故障

-   镜像规则将所有仓库指向了已下线的内部地址；
-   插件仓库与依赖仓库不是同一个域名；
-   制品下载发生重定向，目标域名未纳入网络策略；
-   私有仓库令牌过期，却被误认为407；
-   HTTP仓库被新版本工具拒绝或限制。

排查时应记录实际请求域名与状态码，而不是只看项目文件里写的仓库首页。

## 七、代理认证和仓库认证要分开

代理账号用于通过网络出口，仓库账号用于访问制品，两套凭据不要混用。日志中也要分别脱敏。若收到407，先查看代理的认证挑战；若收到401或403，再查仓库权限。认证机制差异可参考[代理认证与407排查](https://www.jiyueip.com/article/7964)。

## 八、证书信任要看JDK

浏览器信任企业根证书，不代表运行构建的JDK也信任。应确认Maven或Gradle实际使用的Java路径、JDK信任库、代理返回的证书链和系统时间。不要通过关闭证书校验掩盖中间证书缺失或域名不匹配。

## 九、可复现的排查顺序

1.  记录JDK、Maven或Gradle版本及执行用户；
2.  确认实际读取的配置文件路径；
3.  核对代理、非代理主机、仓库和镜像规则；
4.  停止旧Gradle Daemon并执行最小依赖任务；
5.  区分407、401、TLS和连接超时；
6.  核对实际下载域名及重定向；
7.  移除临时配置，保留脱敏变更记录。

## 十、结论

Maven和Gradle代理排查的难点，在于配置层级、JVM、仓库与后台进程叠加。先确认工具真正读取了哪份配置，再按DNS、TCP、代理认证、TLS和仓库认证顺序检查，才能避免把网络故障误修成构建缓存问题。

**Tags:** HTTP代理, 代理技术选型, 服务器运维, 网络故障排查

**Categories:** 行业洞察

---