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程序代理配置指南。
六、仓库配置为什么也会造成“像代理”的故障
- 镜像规则将所有仓库指向了已下线的内部地址；
- 插件仓库与依赖仓库不是同一个域名；
- 制品下载发生重定向，目标域名未纳入网络策略；
- 私有仓库令牌过期，却被误认为407；
- HTTP仓库被新版本工具拒绝或限制。
排查时应记录实际请求域名与状态码，而不是只看项目文件里写的仓库首页。
七、代理认证和仓库认证要分开
代理账号用于通过网络出口，仓库账号用于访问制品，两套凭据不要混用。日志中也要分别脱敏。若收到407，先查看代理的认证挑战；若收到401或403，再查仓库权限。认证机制差异可参考代理认证与407排查。
八、证书信任要看JDK
浏览器信任企业根证书，不代表运行构建的JDK也信任。应确认Maven或Gradle实际使用的Java路径、JDK信任库、代理返回的证书链和系统时间。不要通过关闭证书校验掩盖中间证书缺失或域名不匹配。
九、可复现的排查顺序
- 记录JDK、Maven或Gradle版本及执行用户；
- 确认实际读取的配置文件路径；
- 核对代理、非代理主机、仓库和镜像规则；
- 停止旧Gradle Daemon并执行最小依赖任务；
- 区分407、401、TLS和连接超时；
- 核对实际下载域名及重定向；
- 移除临时配置，保留脱敏变更记录。
十、结论
Maven和Gradle代理排查的难点，在于配置层级、JVM、仓库与后台进程叠加。先确认工具真正读取了哪份配置，再按DNS、TCP、代理认证、TLS和仓库认证顺序检查，才能避免把网络故障误修成构建缓存问题。
