Maven / Gradle 拉依赖超时：镜像换地址，代理换出口

镜像和代理的分工

镜像改的是「去哪里取」。原本要去中央仓库取的依赖，改成去一个国内的镜像仓库取。它是地址替换，前提是那个镜像仓库本身可达、并且确实收录了你需要的那个依赖。

代理改的是「怎么出去」。地址不变，但请求经过一个中间出口发出。它不改变目标，只改变路径。

据 Apache Maven 官方文档对 settings.xml 中 mirrors 与 proxies 的说明，这两者是各自独立的配置段：前者按仓库标识改写请求目标，后者定义请求经由的代理。两段互不替代，可以同时存在，也可以只配其中一个。

把它们混为一谈是最常见的误区：配了镜像却发现某些依赖还是超时，然后继续换镜像地址——而实际卡住的那些依赖可能根本不在镜像的收录范围里，需要回落到原始地址，那一次请求走的是出口这一层，镜像帮不上忙。

为什么有些依赖变快了、有些没有

镜像仓库不是中央仓库的完整复制。它们通常按需缓存：第一个请求某个依赖的人会触发镜像去上游取一次，取回来之后缓存给后来的人。这带来两个后果。

第一，冷门依赖第一次拉取会慢，因为镜像自己也要去上游取一趟；如果镜像到上游的路径本身不好，这一趟同样可能超时。

第二，有些依赖镜像里根本没有——发布在第三方仓库、公司私服、或者作者自己维护的地址上的那些。这类依赖的请求会按配置回落到原始地址，走的是出口这一层。所以「配了镜像还是有几个超时」是完全正常的现象，不代表镜像配错了。

判断方法：看日志里超时的那个 URL 主机名。是镜像的地址，说明镜像这条路有问题；是别的地址，说明这个依赖没走镜像，问题在出口。

配置到底在哪一份文件里生效

这类工具的配置可以来自多个位置：用户目录下的全局配置、项目目录里的配置、命令行参数、以及构建工具自己的运行参数。多个位置同时存在时，实际生效的往往不是你刚改的那一份。

排查的关键动作是让工具自己把生效的配置打印出来，而不是去读你认为它在读的那个文件。多数构建工具都有输出调试信息的开关，打开之后能看到它实际使用的仓库地址和代理设置。这一步省下的时间通常比任何配置技巧都多。

另一个容易被忽略的点是守护进程。一些构建工具会常驻一个后台进程来加速后续构建，而这个进程在启动时读取配置。改了配置却没有重启它，新配置不会生效，表现出来就是「我明明改了没用」。

报错文本怎么读

connect timed out：连接建立不起来，路径层面的问题。看主机名确定是哪一条路。

Could not resolve 或 Could not find：解析阶段失败。依赖坐标写错、版本不存在、或者所有配置的仓库里都没有这个依赖。这不是网络问题，先核对坐标。

checksum validation failed：拿到的文件和记录的哈希不一致。可能是下载不完整，也可能取到了被改动过的内容。清掉本地缓存里的那个依赖重新拉一次，如果反复出现就要查上游。

Received fatal alert 这类握手层报错：连接建立到了加密协商这一步才失败，通常和证书链或者协议版本有关，方向和超时不同。

排查顺序

第一步，看超时的主机名。确定卡住的请求目标是镜像还是原始地址，这一步决定后面查哪一层。

第二步，打印生效配置。打开工具的调试输出，看它实际使用的仓库和代理，不要读你以为它在读的文件。

第三步，重启守护进程。改完配置之后确认常驻进程已经重启，否则新配置不生效。

第四步，清掉本地缓存里那个依赖再试。排除下载不完整留下的残缺文件干扰。

第五步，如果超时的是镜像覆盖不到的原始地址，那问题在出口这一层。逐个依赖找镜像不现实，让整台机器有一条稳定通道通常更直接——构建工具、包管理器、编辑器插件都能一次覆盖。