构建与依赖 / 系统课时
排查依赖冲突与插件失败
排查依赖冲突与插件失败
Maven 构建失败时,先把“依赖解析”和“插件执行”分开取证,再看依赖树、有效 POM 与调试日志。这样可以判断究竟是版本仲裁、Profile 覆盖、仓库解析,还是插件参数与目标本身出了问题,并用同一条命令复验修复结果。
学习目标
- 用
dependency:tree找到同一坐标的版本仲裁和传递路径。 - 用有效 POM、插件描述与
-X日志定位插件配置和解析问题。 - 采用最小改动修复后,使用固定命令确认冲突或失败已经消失。
先把失败分成两条证据链
看到 BUILD FAILURE 后,不要先删 ~/.m2/repository。若错误包含 Could not resolve dependencies、omitted for conflict 或类缺失,优先检查依赖;若包含 Failed to execute goal、PluginResolutionException、MojoFailureException 或 MojoExecutionException,优先检查插件及其配置。

依赖链先执行下面的主诊断命令。-Dverbose 会把被版本冲突省略的节点显示出来;若项目没有冲突,就不会出现 omitted for conflict。
mvn dependency:tree -Dverbose预期输出:具体坐标和版本取决于项目;存在版本冲突时会看到类似结构,最终构建依赖树本身应成功。
[INFO] +- <GROUP_A>:<ARTIFACT_A>:jar:<VERSION_A>:compile
[INFO] | \- <GROUP_X>:<ARTIFACT_X>:jar:<VERSION_X>:compile
[INFO] \- <GROUP_B>:<ARTIFACT_B>:jar:<VERSION_B>:compile
[INFO] \- (<GROUP_X>:<ARTIFACT_X>:jar:<VERSION_Y>:compile - omitted for conflict with <VERSION_X>)
[INFO] BUILD SUCCESS依赖冲突看“谁把谁带进来”
Maven 对同一 groupId:artifactId 的多个版本做依赖仲裁时,常见结果是“路径更近的版本优先”;路径深度相同则与声明顺序有关。不要只看最终选中的版本,还要沿依赖树向上找到引入它的直接依赖,否则很容易在错误位置反复加版本号。
常用修复只有三类:直接依赖明确版本、在 dependencyManagement 统一版本、对不需要的传递依赖做 exclusion。下面是 dependencyManagement 的片段示例,适用于项目已经确认要统一到 httpcore 4.4.16 的情况;它不是“版本越新越好”的推荐值。
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.apache.httpcomponents</groupId>
<artifactId>httpcore</artifactId>
<version>4.4.16</version>
</dependency>
</dependencies>
</dependencyManagement>生效后再次运行 mvn dependency:tree -Dverbose -Dincludes=org.apache.httpcomponents:httpcore,确认最终保留的是 4.4.16,并检查上层库是否与该版本兼容。若直接依赖自己显式写了另一版本,还要同步修改那条直接声明,不能只靠 dependencyManagement 掩盖不一致。
插件失败先还原最终配置
父 POM、Profile、属性和插件管理会共同影响最终插件配置。先生成有效 POM,再对照报错中的插件坐标、版本、goal 和参数;这一步尤其适合排查“明明 POM 写对了,执行时却用了另一组参数”的问题。
mvn help:active-profiles
mvn help:effective-pom -Doutput=effective-pom.xml预期结果:第一条命令列出当前激活的 Profile;第二条命令在项目目录生成 effective-pom.xml,并以 BUILD SUCCESS 结束。Profile 名称与输出路径会随项目和工作目录变化。
[INFO] The following profiles are active:
<ACTIVE_PROFILES>
[INFO] Effective-POM written to: <PATH>/effective-pom.xml
[INFO] BUILD SUCCESS接着用 mvn help:describe -Dplugin=<GROUP_ID>:<ARTIFACT_ID> -Ddetail 查看该插件真实可用的 goals 和参数;把占位坐标替换为报错中的插件。若怀疑插件解析、生命周期绑定或参数注入,再把原失败命令加上 -X 重跑,重点搜索首个 Caused by:、实际插件版本和仓库下载位置,而不是从日志末尾倒推。
用错误类型缩小根因
PluginResolutionException 通常指向插件本体或插件依赖无法从仓库解析,应检查插件坐标、仓库、代理、镜像与认证。MojoFailureException 常见于测试、检查规则等主动判定构建不合格;MojoExecutionException 更偏向插件执行过程抛错或配置不满足要求,仍需以最早的根因堆栈为准。
如果出现“goal 不存在”,先用 help:describe 核对该插件版本是否真的提供这个 goal;如果是“参数无效或类型不匹配”,回到 effective-pom.xml 查最终值来自父 POM、Profile 还是命令行 -D 属性。不要通过随意降级 Maven 或删除整个本地仓库来绕过配置错误。
修复后要复现同一条失败路径
修复依赖冲突后,至少重跑原生命周期命令和一次定向依赖树;修复插件失败后,必须用原先失败的 goal 复验,而不是只执行 mvn validate。例如原失败点在 verify,最终验收也应回到 verify,否则后半段插件根本没有执行。
mvn clean verify预期输出:所有生命周期阶段与绑定插件执行完成,末尾为 BUILD SUCCESS;耗时、模块数量和插件版本属于动态值,实际项目可能不同。
[INFO] Reactor Summary:
<PROJECT_MODULES>
[INFO] BUILD SUCCESS
[INFO] Total time: <TIME>若同一问题只在 CI 出现,再比较 CI 与本机的 mvn -version、Java 版本、激活 Profile、settings.xml 镜像和凭据。只有这些输入一致,依赖树与有效 POM 的对比才有意义。