3.4 依赖下载失败：断粮危机处置手册

3.4 依赖下载失败：断粮危机处置手册

本节摘要：依赖下载失败按根因分四类——构件不存在、仓库不可达、凭证被拒、缓存污染。.lastUpdated 标记会压制重试，checksum 校验守住完整性。本节给出按现象分流的标准处置流程与四类故障的实操命令。

一份被误读三次的报错

新兵值班最常见的求助长这样：

[ERROR] Failed to execute goal on project risk-engine:
Could not resolve dependencies for project com.shop.risk:risk-engine:jar:1.0.0:
Failed to collect dependencies at com.shop.rule:rule-sdk:jar:2.2.0:
Failed to read artifact descriptor for com.shop.rule:rule-sdk:jar:2.2.0:
Could not transfer artifact com.shop.rule:rule-sdk:jar:2.2.0 from/to nexus
  (仓库地址省略): transfer failed for 未知原因
[ERROR] 说明: 无法访问仓库 检查网络或代理
​

值班群里先后出现三个诊断："网断了"（错，公司内网通着）、"私服挂了"（错，别的项目正从私服拉包）、"这个包不存在"（最接近，但也不全对——真实原因是发布方只发了 2.2.0 的 pom 没传 jar）。下载失败的报错文本几乎不区分根因，四类完全不同的故障打出来的是同一句话。所以处置不能从猜开始，要从分流开始。

四类根因与分流流程

第一类：构件缺失。 私有包没发布、开源包坐标拼错（groupId 抄旧版）、版本号不存在（release 版本没有 2.2.1 这个号）。验证手段：

# 用 curl 直接探仓库（地址从报错或 settings 里取）
curl -I 私服地址/repository/releases/com/shop/rule/rule-sdk/2.2.0/rule-sdk-2.2.0.jar
# 返回 200：构件在 问题在别处
# 返回 404：构件不在 找发布方或改坐标
​

第二类：链路故障。 网络抖动、DNS 解析失败、代理设置变更。特征是所有远程仓库同时失败、且换网后恢复。处置以确认链路为主，修复后记得清缓存标记（见第四类）。

第三类：凭证被拒。 私服返回 401 或 403。Maven 的凭证按 server 节点的 id 与仓库 id 匹配，id 对不上等于没配：

<!-- settings.xml：server 的 id 必须与仓库或镜像声明的 id 完全一致 -->
<servers>
  <server>
    <id>nexus-releases</id>
    <username>deploy账号</username>
    <password>加密后的密码</password>
  </server>
</servers>
​

密码建议用 Maven 自带的加密机制（主密码加密后存放），明文密码进共享机器是泄密事故的标准剧本。

第四类：缓存污染。 最隐蔽的一类，也是"网络明明恢复了还是失败"的真凶。第 1.2 节埋的伏笔在这里收线：每次下载失败，Maven 都在本地仓库对应目录写一个 .lastUpdated 文件，记录"何时在哪个仓库没找到"，之后一段时间内不再重试。处置：

# 找到污染点：目标目录下有 lastUpdated 文件 无 jar
# 清理方式一：精确删除该构件目录
# 清理方式二：全库清扫（脚本遍历删除所有 lastUpdated）
# 清理后强制刷新
mvn clean package -U
# -U 让本次构建无视缓存时间窗 立即重查远程
​

另一路污染是文件损坏：下载中断留下半个 jar，或传输损坏的文件。这类故障的爆发点在构建期之后——jar 能被解压但类文件损坏，运行期才炸出奇怪的字节码错误。Maven 对发布件默认做 checksum 校验，校验失败会在日志里警告；把校验策略设为严格（fail 语义）可以把它拦在构建期。

顺手补一个高频子案："同学 A 能下载，同学 B 不能"。同一办公室两台机器行为分叉，先把嫌疑按顺序排：两台机器的 settings 是否一致（镜像与凭证的 diff，第 4.4 节有三份快照对比法）；A 的本地仓库早已有缓存（它根本没在下载，B 才是第一次取）；网络权限按账号或网段区分（内网 ACL 策略）。这类案件的九成，最后都落在"其中一台的缓存里早就躺着那个构件"——用"目录存在与否"取代"能不能上网"作为第一检查点，能省掉大量无效的网络层排查。

现场纪律三条

⚠️ 常见坑一：见失败就删整个本地仓库。本地仓库同时是几十个项目的缓存，全删等于让所有项目重新下载全量依赖，在内网带宽下是半小时起步的群体事故。清创要精确到构件目录。

⚠️ 常见坑二：把 -U 当成万能参数挂在日常构建里。-U 的语义是"强制检查所有 SNAPSHOT 的远程更新"，日常全量挂着它，会把本该命中缓存的构建变成每次都访问远程，构建速度与仓库压力双输。它属于应急参数，不属于常备参数。

💡 关键直觉：下载失败的第一现场永远在报错文本之外——curl 一发探测请求、看一眼本地仓库目录结构、核对 server id，三个动作各十秒钟，比盯着那句"检查网络或代理"猜十分钟有效。养成"先取证再动手"的反射，是断粮处置的全部秘诀。

战报小结

• 报错文本不区分根因：四类故障同一句提示，处置必须走分流流程而非猜测；
• 四类断粮：构件缺失查发布方、链路故障查代理网络、凭证被拒查 server id 匹配、缓存污染清 lastUpdated；
• lastUpdated 是重试压制器：失败留痕导致"恢复后仍失败"，清创精确到构件目录后配 -U 刷新；
• checksum 严格化：把损坏件拦在构建期，代价只是日志里多几行警告；
• 两条纪律：不删整库、不常态挂 -U，两者都是群体级事故的种子。

补给线已稳。下一节把视角从"拿不到弹药"转向"弹药本身有毒"——依赖供应链的三种攻击面与对应防线。