构建与依赖 / 系统课时

排查依赖冲突与插件失败

排查依赖冲突与插件失败

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。

bash
mvn dependency:tree -Dverbose

预期输出:具体坐标和版本取决于项目;存在版本冲突时会看到类似结构,最终构建依赖树本身应成功。

text
[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 的情况;它不是“版本越新越好”的推荐值。

xml
<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 写对了,执行时却用了另一组参数”的问题。

bash
mvn help:active-profiles
mvn help:effective-pom -Doutput=effective-pom.xml

预期结果:第一条命令列出当前激活的 Profile;第二条命令在项目目录生成 effective-pom.xml,并以 BUILD SUCCESS 结束。Profile 名称与输出路径会随项目和工作目录变化。

text
[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,否则后半段插件根本没有执行。

bash
mvn clean verify

预期输出:所有生命周期阶段与绑定插件执行完成,末尾为 BUILD SUCCESS;耗时、模块数量和插件版本属于动态值,实际项目可能不同。

text
[INFO] Reactor Summary:
<PROJECT_MODULES>
[INFO] BUILD SUCCESS
[INFO] Total time:  <TIME>

若同一问题只在 CI 出现,再比较 CI 与本机的 mvn -version、Java 版本、激活 Profile、settings.xml 镜像和凭据。只有这些输入一致,依赖树与有效 POM 的对比才有意义。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

排查依赖冲突与插件失败

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通