1.4 诊断工具箱第一课：依赖树与有效 POM

1.4 诊断工具箱第一课：依赖树与有效 POM

本节摘要：dependency:tree 打印依赖的完整引入路径，是定位"谁把谁带进来"的首选仪器；help:effective-pom 打印继承合并后的最终构建事实，是核对"配置到底生效没有"的权威依据。本节以一次新兵值班为线索，讲清两件工具的用法、输出格式与解读要点。

第一次独立值班

新工程师小周第一次独立值班，收到测试同学反馈：risk-engine 在测试环境启动失败，报错信息是某个类找不到，但这个类明明在项目的依赖列表里。前辈留下一句话："先打树，再打有效 POM，两份输出放在一起看。" 十分钟后小周拿着两份输出回来，问题已经定位：那个类所在的构件被另一个依赖的旧版本顶掉了。

这两件工具为什么排在诊断箱最上层？因为依赖类故障的提问方式永远是两个："这个包是从哪条路径进来的"（依赖树回答）和"我写的配置最终变成了什么"（有效 POM 回答）。先把两个问题都变成可打印的证据，再谈修复。

依赖树：把引路人都画出来

依赖树插件属于 maven-dependency-plugin，最基础的调用一行：

mvn dependency:tree
# 精简后的输出示例：
# com.shop.risk:risk-engine:jar:1.0.0
# +- com.fasterxml.jackson.core:jackson-databind:jar:2.13.4:compile
# |  +- com.fasterxml.jackson.core:jackson-annotations:jar:2.13.4:compile
# |  \- com.fasterxml.jackson.core:jackson-core:jar:2.13.4:compile
# +- com.shop.rule:rule-sdk:jar:2.1.0:compile
# |  \- com.fasterxml.jackson.core:jackson-databind:jar:2.12.7:compile - omitted for duplicate
# \- junit:junit:jar:4.13.2:test
​

读树有三条规则。缩进即路径：每一层缩进表示"通过上一行的依赖传递引入"。竖线与折线：加号或竖线开头表示同层还有后续，反斜杠表示该层最后一个。omitted 标记是关键情报：示例中 rule-sdk 想引入 2.12.7 版的 jackson-databind，但 Maven 调解后丢弃了它（因为主声明直接依赖了 2.13.4，路径更近），树里如实记录为 omitted for duplicate。被 omit 的版本正是第 3 章依赖战争的头号当事人——现在先记住：看到 omitted，就意识到这里发生过一次版本裁决。

参数层面有三个高频用法：

# 只看某个构件的引入路径，过滤是按 group 与 artifact 前缀匹配
mvn dependency:tree -Dincludes=com.fasterxml.jackson.core
# 输出只剩 jackson 三兄弟及其父链，一眼看清它们从哪来

# 显示被调解丢弃的重复版本，默认树里只写 omitted 不展开
mvn dependency:tree -Dverbose
# 多出诸如 2.12.7 omitted for conflict with 2.13.4 的行

# 导出成文件贴进工单
mvn dependency:tree -DoutputFile=tree.txt
​

图：risk-engine 首屏依赖树（示意）

有效 POM：把合并结果摊在桌面上

第二件仪器解决"配置疑云"。前文说过，实际生效的 POM 是当前文件、各级父 POM、超级 POM、激活 Profile 合并的结果。当"我明明写了这个配置"与"它好像没生效"同时成立时，唯一可靠的裁判是打印有效 POM：

mvn help:effective-pom
# 控制台输出完整合并结果，重定向保存便于对比
mvn help:effective-pom -Doutput=effective.xml

# 顺手的姊妹工具：查看合并后的 settings（镜像、凭证、仓库）
mvn help:effective-settings
​

解读时抓三个位置。一是 dependencies 段：确认某依赖的版本与 scope 是否与预期一致（版本若来自 dependencyManagement，这里能看到最终数字）。二是 build 的 plugins 段：确认插件配置覆盖是否生效、版本被谁锁定。三是 repositories 段：确认远程仓库与镜像改道是否符合预期——下载类故障在这里经常能找到根因，比如镜像规则把私服请求劫走了。

💡 关键直觉：诊断配置问题的顺序是"先打印事实，再读代码想象"。开发者习惯盯着自己写的 POM 推理，但合并规则的细节（哪个父级覆盖哪个子级、Profile 何时介入）很容易记错。effective-pom 一秒钟给出真相，成本远低于一次错误的推理。

两件工具的组合拳：依赖树回答"classpath 里有什么、从哪来"，有效 POM 回答"这些声明是在什么配置下解析的"。小周那次值班，正是靠树里的 omitted 行锁定冲突构件，再靠有效 POM 确认父 POM 的 dependencyManagement 没管住这个构件，两步完成定位。

补一件常被忽略的姊妹仪器：依赖列表的扁平视图。

mvn dependency:list
# 输出示例（去重后的最终入场清单）：
# com.fasterxml.jackson.core:jackson-databind:jar:2.13.4:compile
# com.shop.rule:rule-sdk:jar:2.1.0:compile
# junit:junit:jar:4.13.2:test
# 共 146 项
​

树适合追路径，列表适合清点存量——第 3.5 节做依赖审计（统计第三方库构成、按组织分组清点）时，扁平列表比树好读得多。两份输出配合 -DincludeGroupIds 按组织过滤，一份"我们到底用了某公司的哪些库"的清单一分钟出炉。

战报小结

• dependency:tree 是第一勘查仪器：缩进读路径、omitted 读裁决、-Dincludes 过滤、-Dverbose 展示全部落选版本；
• 有效 POM 是配置终审法官：打印合并结果再推理，禁止凭记忆猜继承关系；
• effective-settings 管下载类疑云：镜像改道与仓库声明都在它的输出里现形；
• 两件工具配合作战：树定位构件来源，有效 POM 核对解析环境，覆盖绝大多数依赖故障的定位需求。

第 1 章到此收束：你已经认识地形、会用频道、手握勘查仪器。第 2 章拆开构建机器本身——生命周期如何分阶段推进、插件如何绑定执行，那台你天天按回车的机器，内部结构将完全摊开。