dependencyManagement 已声明，为什么最终运行包仍然缺依赖？
排查 Maven 依赖问题时，经常会遇到一种反直觉现象：POM 已经声明了目标版本，mvn package 也成功结束，但最终可执行 Jar、WAR 或服务器 lib 中仍然没有目标依赖。
问题通常不在"版本写错了"，而在两个更基础的边界上：
dependencyManagement所在位置是否真的覆盖最终打包模块？- 目标依赖是否通过直接依赖或传递依赖进入了该模块的依赖图？
dependencyManagement 只负责管理已经进入依赖图的依赖版本。它不会主动引入一个 Jar，也不会跨越没有继承或 BOM 导入关系的模块边界。
先分清两个不同问题
问题一：版本管理没有覆盖最终打包模块
假设一个多模块项目包含 dependency-policy 和 application 两个平级模块。版本管理写在 dependency-policy/pom.xml 中，但最终产物由 application 生成。
平级模块之间不会自动继承 dependencyManagement。即使 dependency-policy 自己的依赖树已经解析到新版本，也不能证明 application 看到了同一管理配置。
版本管理要影响 application，至少需要满足一种关系：
- 配置位于
application的父 POM 或祖先 POM； application在自己的dependencyManagement中导入了对应 BOM；application自己声明了该版本管理。
下面是一个通用化的 BOM 导入示例：
xml
<!-- 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 是否会进入包。
问题二：只有版本管理，没有真实依赖
下面这段配置只定义了版本：
xml
<!-- 这里只管理版本，不会主动把 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 中建立依赖关系：
xml
<!-- 真实依赖引用；版本由 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：证明最终模块看到了什么
必须对真正产出运行包的模块执行检查，而不是只检查本次修改所在模块：
powershell
# 生成最终打包模块的 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：证明依赖是否进入解析图
powershell
# 只查看最终打包模块中的目标依赖
mvn -pl :application dependency:tree `
"-Dincludes=com.example:archive-lib"判断结果时要同时看三项：
- 是否存在目标坐标；
- 最终解析版本是否符合预期；
- scope 是否会进入目标产物。
如果 effective POM 中有版本管理，但依赖树没有目标坐标，通常说明只做了版本管理，没有任何真实依赖路径。
4. 最终运行包：证明物理产物里有什么
依赖树正确后，重新构建并检查新产物。不要拿修改前遗留的 target 文件作为证据。
powershell
# 清理旧产物并构建最终模块；是否跳过测试应按项目要求决定
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-'不同产物的检查位置不同：
| 产物类型 | 常见依赖位置 | 需要确认的内容 |
|---|---|---|
| Spring Boot 可执行 Jar | BOOT-INF/lib |
目标 Jar 名称和版本 |
| WAR | WEB-INF/lib |
容器实际随包加载的依赖 |
| 解压式发行包 | lib |
核心 Jar 与配套依赖 |
| 外置服务器依赖 | 服务器 lib 或启动 classpath |
新旧版本是否并存、加载顺序 |
jar tf 能证明 Jar 条目存在，但仍不能证明应用已经成功启动。
5. 真实运行：证明启动和关键功能是否可用
最后一层至少需要根据系统风险完成这些检查：
- 使用实际部署方式启动应用；
- 从启动日志确认加载路径和版本；
- 对依赖相关功能做最小 smoke test；
- 检查旧版本是否仍在外置
lib或额外 classpath 中； - 基础组件升级时，核对 JDK、框架和传递依赖兼容性。
如果当前证据只有 mvn package 成功和目标 Jar 条目存在，准确表述应是"构建产物验证通过"，不能写成"运行验证通过"。
两类已验证现象说明了什么
在既有构建记录中，两类问题分别得到过产物级验证：
- 版本管理最初位于不覆盖最终打包模块的下游模块中。将管理配置放到真实共同父级后，最终包中的目标依赖版本才发生变化。
- 目标库最初只出现在
dependencyManagement中。补充真实dependency后，依赖树出现目标坐标，重新构建的可执行 Jar 也出现对应条目。
这些事实支持本文关于 Maven 解析与打包边界的结论，但验证范围止于本地依赖解析和构建产物检查。现有证据不能推出生产环境启动、业务功能、性能或所有版本兼容性已经验证通过。
常见误区
只看根 POM，不看最终模块
根 POM 中存在配置，不代表目标模块一定继承了它。聚合关系和继承关系是两回事，最终应以目标模块的 effective POM 为准。
只检查修改模块的依赖树
局部模块解析正确，不代表最终发包模块解析正确。命令中的 -pl 应指向真正产出运行包的模块。
构建成功就认为依赖已经生效
构建成功只说明 Maven 生命周期完成。目标依赖可能根本没有进入图，也可能以不会打包的 scope 出现，还可能被插件重新布局或排除。
看到依赖树就跳过产物检查
依赖树描述 Maven 的解析结果，最终包描述交付物的物理内容。对于可执行 Jar、WAR、assembly 或自定义打包插件，两者都需要检查。
手工替换服务器 lib 时只换一个 Jar
直接替换服务器 lib 时，应从已经验证的最终包和依赖树反推清单，同时处理旧版本残留。只替换核心 Jar，可能遗漏必要传递依赖，也可能因 classpath 顺序继续加载旧版本。
可复用检查清单
遇到"版本已经声明但依赖仍未生效"时，可以按下面的顺序处理：
- 找到真正产出运行包的 Maven 模块。
- 确认版本管理来自父 POM、祖先 POM、导入 BOM 或当前模块。
- 生成该模块的 effective POM，确认管理版本可见。
- 在该模块运行
dependency:tree，确认坐标、版本和 scope。 - 如果依赖图中不存在目标坐标，检查真实
dependency、传递路径、optional和exclusions。 - 清理旧产物后重新构建，避免使用过期 Jar。
- 按产物类型检查
BOOT-INF/lib、WEB-INF/lib或发行包lib。 - 外置部署时检查服务器旧 Jar、classpath 和加载顺序。
- 将"构建产物验证"与"真实运行验证"分开记录。
结语
dependencyManagement 回答的是"依赖进入图后使用哪个版本"，不是"哪些依赖必须进入图"。多模块项目还要再加一个前提：这份管理配置必须对最终打包模块可见。
因此，可靠的验收顺序不是"POM 已修改，所以问题已解决"，而是"目标模块看到配置、依赖进入解析图、最终产物包含目标 Jar、真实环境完成运行验证"。每一步都只证明自己的那一层。
周末可提供 Java/Spring 远程问题诊断，欢迎通过平台私信交流。