Maven dependencyManagement 已声明却仍缺 Jar：如何验证最终运行包

dependencyManagement 已声明，为什么最终运行包仍然缺依赖？

排查 Maven 依赖问题时，经常会遇到一种反直觉现象：POM 已经声明了目标版本，mvn package 也成功结束，但最终可执行 Jar、WAR 或服务器 lib 中仍然没有目标依赖。

问题通常不在“版本写错了”，而在两个更基础的边界上：

dependencyManagement 只负责管理已经进入依赖图的依赖版本。它不会主动引入一个 Jar，也不会跨越没有继承或 BOM 导入关系的模块边界。

先分清两个不同问题

问题一：版本管理没有覆盖最终打包模块

假设一个多模块项目包含 dependency-policy 和 application 两个平级模块。版本管理写在 dependency-policy/pom.xml 中，但最终产物由 application 生成。

平级模块之间不会自动继承 dependencyManagement。即使 dependency-policy 自己的依赖树已经解析到新版本，也不能证明 application 看到了同一管理配置。

版本管理要影响 application，至少需要满足一种关系：

• 配置位于 application 的父 POM 或祖先 POM；
• application 在自己的 dependencyManagement 中导入了对应 BOM；
• application 自己声明了该版本管理。

下面是一个通用化的 BOM 导入示例：

<!– application/pom.xml：显式导入统一依赖管理 –>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>com.example</groupId>
<artifactId>dependency-bom</artifactId>
<version>1.0.0</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>

这里解决的是“最终模块能否看到版本管理”，还没有回答目标 Jar 是否会进入包。

问题二：只有版本管理，没有真实依赖

下面这段配置只定义了版本：

<!– 这里只管理版本，不会主动把 archive-lib 加入依赖图 –>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>com.example</groupId>
<artifactId>archive-lib</artifactId>
<version>2.0.0</version>
</dependency>
</dependencies>
</dependencyManagement>

如果 archive-lib 既不是直接依赖，也没有被其他依赖传递引入，Maven 不会下载并打包它。需要它参与运行时，必须在真实的 dependencies 中建立依赖关系：

<!– 真实依赖引用；版本由 dependencyManagement 统一提供 –>
<dependencies>
<dependency>
<groupId>com.example</groupId>
<artifactId>archive-lib</artifactId>
</dependency>
</dependencies>

如果目标库本应由另一个组件传递引入，则不应机械地补一条直接依赖。先检查它是否被 exclusions 排除、是否标记为 optional，以及当前 scope 是否会进入运行包，再决定修复位置。

一条完整的验证链

下面五个层级证明的是不同事实，不能用前一个替代后一个。

#mermaid-svg-Ee6eEsFpPNI6v9RR{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-Ee6eEsFpPNI6v9RR .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-Ee6eEsFpPNI6v9RR .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-Ee6eEsFpPNI6v9RR .error-icon{fill:#552222;}#mermaid-svg-Ee6eEsFpPNI6v9RR .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-Ee6eEsFpPNI6v9RR .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-Ee6eEsFpPNI6v9RR .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-Ee6eEsFpPNI6v9RR .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-Ee6eEsFpPNI6v9RR .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-Ee6eEsFpPNI6v9RR .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-Ee6eEsFpPNI6v9RR .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-Ee6eEsFpPNI6v9RR .marker{fill:#333333;stroke:#333333;}#mermaid-svg-Ee6eEsFpPNI6v9RR .marker.cross{stroke:#333333;}#mermaid-svg-Ee6eEsFpPNI6v9RR svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-Ee6eEsFpPNI6v9RR p{margin:0;}#mermaid-svg-Ee6eEsFpPNI6v9RR .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-Ee6eEsFpPNI6v9RR .cluster-label text{fill:#333;}#mermaid-svg-Ee6eEsFpPNI6v9RR .cluster-label span{color:#333;}#mermaid-svg-Ee6eEsFpPNI6v9RR .cluster-label span p{background-color:transparent;}#mermaid-svg-Ee6eEsFpPNI6v9RR .label text,#mermaid-svg-Ee6eEsFpPNI6v9RR span{fill:#333;color:#333;}#mermaid-svg-Ee6eEsFpPNI6v9RR .node rect,#mermaid-svg-Ee6eEsFpPNI6v9RR .node circle,#mermaid-svg-Ee6eEsFpPNI6v9RR .node ellipse,#mermaid-svg-Ee6eEsFpPNI6v9RR .node polygon,#mermaid-svg-Ee6eEsFpPNI6v9RR .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-Ee6eEsFpPNI6v9RR .rough-node .label text,#mermaid-svg-Ee6eEsFpPNI6v9RR .node .label text,#mermaid-svg-Ee6eEsFpPNI6v9RR .image-shape .label,#mermaid-svg-Ee6eEsFpPNI6v9RR .icon-shape .label{text-anchor:middle;}#mermaid-svg-Ee6eEsFpPNI6v9RR .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-Ee6eEsFpPNI6v9RR .rough-node .label,#mermaid-svg-Ee6eEsFpPNI6v9RR .node .label,#mermaid-svg-Ee6eEsFpPNI6v9RR .image-shape .label,#mermaid-svg-Ee6eEsFpPNI6v9RR .icon-shape .label{text-align:center;}#mermaid-svg-Ee6eEsFpPNI6v9RR .node.clickable{cursor:pointer;}#mermaid-svg-Ee6eEsFpPNI6v9RR .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-Ee6eEsFpPNI6v9RR .arrowheadPath{fill:#333333;}#mermaid-svg-Ee6eEsFpPNI6v9RR .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-Ee6eEsFpPNI6v9RR .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-Ee6eEsFpPNI6v9RR .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-Ee6eEsFpPNI6v9RR .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-Ee6eEsFpPNI6v9RR .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-Ee6eEsFpPNI6v9RR .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-Ee6eEsFpPNI6v9RR .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-Ee6eEsFpPNI6v9RR .cluster text{fill:#333;}#mermaid-svg-Ee6eEsFpPNI6v9RR .cluster span{color:#333;}#mermaid-svg-Ee6eEsFpPNI6v9RR div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-Ee6eEsFpPNI6v9RR .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-Ee6eEsFpPNI6v9RR rect.text{fill:none;stroke-width:0;}#mermaid-svg-Ee6eEsFpPNI6v9RR .icon-shape,#mermaid-svg-Ee6eEsFpPNI6v9RR .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-Ee6eEsFpPNI6v9RR .icon-shape p,#mermaid-svg-Ee6eEsFpPNI6v9RR .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-Ee6eEsFpPNI6v9RR .icon-shape .label rect,#mermaid-svg-Ee6eEsFpPNI6v9RR .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-Ee6eEsFpPNI6v9RR .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-Ee6eEsFpPNI6v9RR .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-Ee6eEsFpPNI6v9RR :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

POM diff

effective POM

dependency:tree

最终构建产物

真实运行 classpath

文字版流程是：先确认配置改动，再确认最终模块看到的有效配置，然后确认解析后的依赖图，接着检查物理产物，最后才验证真实运行环境。

1. POM diff：只证明配置被修改

代码评审里看到属性、BOM 或 dependencyManagement 发生变化，只能说明配置文本变了。它不能证明最终打包模块继承了这段配置，也不能证明目标依赖进入了依赖图。

2. effective POM：证明最终模块看到了什么

必须对真正产出运行包的模块执行检查，而不是只检查本次修改所在模块：

# 生成最终打包模块的 effective POM
mvn –pl :application help:effective-pom `
–Doutput=target/effective-pom.xml

# 检查目标坐标和版本管理是否出现在有效配置中
Select-String –Path .\\application\\target\\effective-pom.xml `
–Pattern 'archive-lib|2.0.0'

如果目标版本没有出现在该模块的 effective POM 中，应先修复父子关系或 BOM 导入关系。此时继续检查旧产物没有意义。

3. dependency:tree：证明依赖是否进入解析图

# 只查看最终打包模块中的目标依赖
mvn –pl :application dependency:tree `
"-Dincludes=com.example:archive-lib"

判断结果时要同时看三项：

• 是否存在目标坐标；
• 最终解析版本是否符合预期；
• scope 是否会进入目标产物。

如果 effective POM 中有版本管理，但依赖树没有目标坐标，通常说明只做了版本管理，没有任何真实依赖路径。

4. 最终运行包：证明物理产物里有什么

依赖树正确后，重新构建并检查新产物。不要拿修改前遗留的 target 文件作为证据。

# 清理旧产物并构建最终模块；是否跳过测试应按项目要求决定
mvn –pl :application –am clean package –DskipTests

# Spring Boot 可执行 Jar 通常检查 BOOT-INF/lib
jar tf .\\application\\target\\application.jar |
Select-String 'BOOT-INF/lib/archive-lib-'

不同产物的检查位置不同：

jar tf 能证明 Jar 条目存在，但仍不能证明应用已经成功启动。

5. 真实运行：证明启动和关键功能是否可用

最后一层至少需要根据系统风险完成这些检查：

• 使用实际部署方式启动应用；
• 从启动日志确认加载路径和版本；
• 对依赖相关功能做最小 smoke test；
• 检查旧版本是否仍在外置 lib 或额外 classpath 中；
• 基础组件升级时，核对 JDK、框架和传递依赖兼容性。

如果当前证据只有 mvn package 成功和目标 Jar 条目存在，准确表述应是“构建产物验证通过”，不能写成“运行验证通过”。

两类已验证现象说明了什么

在既有构建记录中，两类问题分别得到过产物级验证：

这些事实支持本文关于 Maven 解析与打包边界的结论，但验证范围止于本地依赖解析和构建产物检查。现有证据不能推出生产环境启动、业务功能、性能或所有版本兼容性已经验证通过。

常见误区

只看根 POM，不看最终模块

根 POM 中存在配置，不代表目标模块一定继承了它。聚合关系和继承关系是两回事，最终应以目标模块的 effective POM 为准。

只检查修改模块的依赖树

局部模块解析正确，不代表最终发包模块解析正确。命令中的 -pl 应指向真正产出运行包的模块。

构建成功就认为依赖已经生效

构建成功只说明 Maven 生命周期完成。目标依赖可能根本没有进入图，也可能以不会打包的 scope 出现，还可能被插件重新布局或排除。

看到依赖树就跳过产物检查

依赖树描述 Maven 的解析结果，最终包描述交付物的物理内容。对于可执行 Jar、WAR、assembly 或自定义打包插件，两者都需要检查。

手工替换服务器 lib 时只换一个 Jar

直接替换服务器 lib 时，应从已经验证的最终包和依赖树反推清单，同时处理旧版本残留。只替换核心 Jar，可能遗漏必要传递依赖，也可能因 classpath 顺序继续加载旧版本。

可复用检查清单

遇到“版本已经声明但依赖仍未生效”时，可以按下面的顺序处理：

结语

dependencyManagement 回答的是“依赖进入图后使用哪个版本”，不是“哪些依赖必须进入图”。多模块项目还要再加一个前提：这份管理配置必须对最终打包模块可见。

因此，可靠的验收顺序不是“POM 已修改，所以问题已解决”，而是“目标模块看到配置、依赖进入解析图、最终产物包含目标 Jar、真实环境完成运行验证”。每一步都只证明自己的那一层。

周末可提供 Java/Spring 远程问题诊断，欢迎通过平台私信交流。