构建与依赖 / 系统课时
排查依赖下载与仓库问题
排查依赖下载与仓库问题
依赖下载失败不要先删整个 .m2。更有效的顺序是先确认 Maven 实际使用的 settings、镜像和离线状态,再根据 HTTP/TLS 错误判断网络或认证问题,最后只清理受影响的本地缓存,并用 -U 处理需要重新检查的 SNAPSHOT 或此前缺失的构件。
学习目标
- 用有效 settings 和调试日志确认 Maven 最终访问了哪个仓库,以及是否被镜像、代理或离线模式改写。
- 根据 401、403、404、407、TLS 和超时等现象快速定位认证、权限、仓库路径或网络问题。
- 精确清理损坏缓存,并正确使用
-U、-o和 SNAPSHOT 更新策略。
先确认 Maven 实际采用的配置
Maven 的用户级配置通常在 ${user.home}/.m2/settings.xml,安装级配置还可能来自 Maven 安装目录。先把合并后的有效配置输出到文件,比直接猜 POM 或 settings 哪一处生效更可靠。
mvn help:effective-settings -Doutput=effective-settings.xml预期结果:当前目录生成 effective-settings.xml,命令最终显示 BUILD SUCCESS。打开文件后重点检查 <offline>、<mirrors>、<servers>、<proxies>;如果你传了 -s <PATH>,则要确认 <PATH> 指向的确是本次希望使用的 settings。
再用一次带调试日志的解析动作复现问题。-X 输出仓库选择、传输和异常细节;-U 会要求 Maven 重新检查远端的 SNAPSHOT,并重新检查此前缺失的 release。
mvn -X -U compile预期结果:正常项目最终出现 BUILD SUCCESS;失败时保留从 Downloading from ...、Could not transfer artifact ... 到根异常的完整片段,不要只截最后一行 BUILD FAILURE。

核对镜像和私服认证
私服下载最容易错在 id。当仓库被 mirror 替换后,Maven 连接的是 mirror 的 id,<servers> 中提供凭据的 <server><id> 必须与实际连接目标匹配。下面是片段示例,依赖上下文为用户级 settings.xml;nexus.company.example 是文档示例域名,使用时替换为真实私服地址。
<settings>
<mirrors>
<mirror>
<id>corp-mirror</id>
<mirrorOf>*</mirrorOf>
<url>https://nexus.company.example/repository/maven-public/</url>
</mirror>
</mirrors>
<servers>
<server>
<id>corp-mirror</id>
<username>${env.REPO_USER}</username>
<password>${env.REPO_TOKEN}</password>
</server>
</servers>
</settings>生效结果:所有仓库请求会被这个 mirror 接管,认证凭据从环境变量读取。只有当该私服能够代理或提供项目需要的全部仓库时才使用 mirrorOf=*;否则应缩小匹配范围。不要把用户名和令牌提交进项目 POM。
错误现象可以直接映射到下一步动作:
| 现象 | 优先检查 | 常见修复 |
|---|---|---|
401 Unauthorized |
<server><id>、用户名或令牌 |
让 server id 与实际 mirror/repository id 一致,更新凭据 |
403 Forbidden |
账号权限、仓库读权限 | 给账号开放目标仓库或路径的读取权限 |
407 Proxy Authentication Required |
<proxies> |
配置代理账号,确认只有一个代理处于 active |
404 Not Found |
groupId、artifactId、version、仓库路径 | 确认版本真实存在,并确认 release/SNAPSHOT 在正确仓库 |
PKIX path building failed |
JVM 信任库、公司 TLS 代理证书 | 将受信 CA 正确导入构建所用 JDK 的 truststore |
| 连接超时或 DNS 失败 | 代理、VPN、防火墙、DNS | 先恢复到仓库主机的网络可达性,再重试 Maven |
精确修复本地缓存
下载中断可能留下损坏的 JAR、POM 或失败标记。不要先删除整个 ${user.home}/.m2/repository,那会迫使所有项目重新下载。优先只清理确认有问题的坐标;Maven Dependency Plugin 的 purge-local-repository 可以做定点删除。
下面以 org.slf4j:slf4j-api 为例。manualInclude 会从本地仓库移除指定构件;随后 compile 在项目需要它时重新解析和下载。
mvn dependency:purge-local-repository -DmanualInclude=org.slf4j:slf4j-api
mvn -U compile预期结果:清理目标执行成功;如果当前项目确实依赖 slf4j-api,后续构建会重新下载该构件,并最终出现 BUILD SUCCESS。若依赖仍失败,应回到远端仓库或认证问题,而不是继续扩大删除范围。
对单个坐标手工检查时,可进入其本地仓库目录查看是否存在 .lastUpdated 文件、大小异常的 JAR 或 POM。确认远端已可访问后,再删除该坐标对应版本目录并执行 mvn -U compile,而不是删除整个仓库。
区分离线模式和 SNAPSHOT 更新
-o 表示离线构建,只允许使用本地已有构件。它适合断网环境下验证缓存是否完整,却不适合“修复下载失败”;缺失任意依赖或插件时,离线模式只会更快暴露问题。
mvn -o verify预期结果:如果所需依赖和插件都已在本地,构建可以到达 BUILD SUCCESS;如果缓存不完整,会直接报告离线状态下无法访问远端或无法解析缺失构件。
SNAPSHOT 是否重新检查还受仓库更新策略影响,常见值是 always、daily、interval:X 和 never。临时排查时优先用 -U 强制本次检查;反过来,-nsu 会抑制 SNAPSHOT 更新;排障时若发现脚本带了它要先移除。Maven 3.9.0+ 还支持通过 MAVEN_ARGS 注入参数,因此也要检查该环境变量。
最后再执行一次不带 -X 的普通构建作为验收。只有在有效 settings 指向正确仓库、认证成功、本地缓存正常且 SNAPSHOT 策略符合预期时,问题才算真正解决;单次“删缓存后碰巧成功”不足以证明根因已处理。