1. 从一次依赖版本失控说起
如果你维护过稍微大一点的Java项目，大概率遇到过这种场景：三个子模块各自声明了同一个库的不同版本，本地跑没问题，一上CI就报NoSuchMethodError。排查半天发现是A模块传递依赖带进来了一个旧版本，而B模块又显式声明了新版本，Maven的“最近优先”仲裁规则一搅和，最终生效的版本跟你预期的完全不是一回事。
这类问题的根源，往往不在代码，而在pom.xml的组织方式。Maven给了我们两个极其关键的工具来治理这种混乱：<parent>和<dependencyManagement>。但很多人对这两个东西的理解停留在“抄一份Spring Boot的parent就完事了”，至于它到底怎么工作、什么时候该用哪个、两者能不能互相替代，其实并不清楚。
这篇内容就是围绕这两个标签展开的。我会从它们各自的职责边界讲起，拆解依赖版本仲裁的底层逻辑，然后给出多模块项目里一套可落地的组织方案。适合已经会写pom.xml、但被多模块依赖管理折磨过的开发者，也适合想彻底搞明白“为什么我的版本没生效”的人。读完你至少能做到：知道版本冲突时该改哪里、知道parent和dependencyManagement各自解决什么问题、知道怎么设计一套不会随模块增多而失控的依赖结构。
2. parent标签到底继承了什么
2.1 parent不是“复制粘贴”，而是POM的继承链
很多人把<parent>理解成“把父POM的内容复制过来”，这个直觉是错的。Maven的parent机制本质上是POM对象的继承，子POM在构建时会先加载父POM，然后把自己的配置合并上去。合并的规则不是简单覆盖，而是分字段有不同策略。
具体来说，子POM能继承的东西包括：
<groupId>、<version>（如果子POM没写，默认继承父的）<properties>：父POM里定义的属性，子POM可以直接用${xxx}引用<dependencies>：父POM里声明的依赖，子POM会全部继承，这是最容易踩坑的地方<dependencyManagement>：只继承“版本声明”，不实际引入依赖<build>下的<pluginManagement>、<plugins>、<resources>等<repositories>、<distributionManagement>等
这里有个关键区别：<dependencies>是实打实引入，<dependencyManagement>只是声明版本。父POM里写<dependencies>，所有子模块都会自动带上这个依赖，不管它需不需要。这就是为什么好的父POM通常只放<dependencyManagement>，而把实际依赖留给子模块自己声明。
2.2 继承链的查找顺序与relativePath
子POM声明parent时，Maven怎么找到父POM？默认顺序是这样的：
- 先看
<relativePath>指定的路径（默认是../pom.xml） - 如果相对路径找不到，去本地仓库找
- 本地仓库没有，去远程仓库拉
<relativePath>这个标签经常被忽略，但它在多模块项目里很重要。默认值../pom.xml意味着Maven会先去上一级目录找父POM。如果你项目结构是parent/pom.xml和parent/module-a/pom.xml，那默认就能找到。但如果结构是root/parent/pom.xml和root/module-a/pom.xml，就得显式写<relativePath>../parent/pom.xml</relativePath>。
提示：如果父POM还没安装到本地仓库，而
relativePath又写错了，Maven会直接报Non-resolvable parent POM。这个错误九成是路径问题，不是网络问题。
还有一个细节：<relativePath/>写成空标签，表示强制从仓库查找，不走相对路径。这在CI环境里有时有用，避免因为目录结构差异导致找到错误的父POM。
2.3 parent的版本必须显式声明
一个容易被忽略的点：<parent>里的<version>是必填的（除非用CI-friendly的${revision}占位符）。你不能像<dependencyManagement>那样省略版本让Maven去猜。这意味着每次父POM升版本，所有子模块的parent版本都得跟着改。
这就引出了flatten-maven-plugin或者${revision}这类方案的价值。用${revision}可以让父子版本统一由一个属性控制，改一处全生效。不过这是另一个话题，这里先记住：parent版本是硬编码的，升级时要么手动改，要么用工具批量改。
3. dependencyManagement的“声明”与“引入”分离
3.1 它只负责定版本，不负责拉依赖
<dependencyManagement>最核心的一句话概括：它只声明依赖的版本和scope，不实际引入依赖。子模块要用某个依赖，还是得在自己的<dependencies>里写一遍，但可以不写版本号，Maven会去父POM的dependencyManagement里找。
这个设计的好处非常明显。假设你有20个子模块，其中15个要用jackson-databind。如果不用dependencyManagement，你得在15个地方各写一遍版本号，升级时改15处。用了之后，版本只在父POM写一次，子模块只写groupId和artifactId。
<!-- 父POM --> <dependencyManagement> <dependencies> <dependency> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-databind</artifactId> <version>2.15.2</version> </dependency> </dependencies> </dependencyManagement> <!-- 子POM --> <dependencies> <dependency> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-databind</artifactId> <!-- 不写version，从父POM继承 --> </dependency> </dependencies>3.2 传递依赖的版本也会被它管住
这是dependencyManagement最强大也最容易被低估的能力：它能覆盖传递依赖的版本。
举个例子，你的项目依赖了库A，库A又依赖了guava:18.0。但你想用guava:32.0。如果直接在<dependencies>里声明guava:32.0，Maven的“最近优先”规则会让你的直接声明生效，这没问题。但如果库A和库B都传递依赖了不同版本的guava，而你又没直接声明，仲裁结果就不可控了。
这时候在dependencyManagement里声明guava:32.0，所有传递进来的guava都会被强制统一到32.0。这个机制是治理“依赖地狱”的核心武器。
注意：
dependencyManagement的覆盖是无条件的，它不参与“最近优先”仲裁，而是直接指定最终版本。所以它既能解决问题，也能制造问题——如果你声明了一个不兼容的版本，所有模块都会跟着遭殃。
3.3 import scope：把别人的dependencyManagement搬进来
<dependencyManagement>里有个特殊的scope叫import，配合<type>pom</type>使用，可以把另一个POM的dependencyManagement整块导入进来。
<dependencyManagement> <dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-dependencies</artifactId> <version>3.1.0</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement>这就是Spring Boot项目里常见的用法。spring-boot-dependencies这个POM里全是dependencyManagement，import进来之后，你用Spring Boot生态的库都不用写版本号。
import有个限制：只能导入dependencyManagement，不能导入dependencies。而且导入的POM必须已经发布到仓库，不能是本地未安装的模块。另外，import的依赖如果和当前POM的dependencyManagement有冲突，当前POM的声明优先级更高。
4. 两者协作时的优先级与覆盖规则
4.1 直接声明 > dependencyManagement > 传递依赖
当同一个依赖在多个地方出现版本声明时，Maven的优先级从高到低是：
- 子POM的
<dependencies>里直接写的<version> - 父POM（或import的POM）的
<dependencyManagement>里的版本 - 传递依赖带来的版本（按“最近优先”仲裁）
这个顺序解释了很多“为什么我改了版本没生效”的问题。如果你在子POM的<dependencies>里写了版本，那dependencyManagement就管不住它。反过来，如果你想让dependencyManagement统一管理，子POM里就不要写version。
4.2 多层parent的继承与覆盖
实际项目里经常有多层parent：company-parent→project-parent→module。这时候dependencyManagement的合并规则是就近覆盖：子POM的dependencyManagement会覆盖父POM的同名声明，而不是合并版本。
假设company-parent声明了guava:30.0，project-parent声明了guava:32.0，那project-parent及其子模块最终用的是32.0。如果project-parent没声明，就用30.0。
这个规则意味着：越靠近子模块的parent，优先级越高。所以公司级的parent适合放“兜底版本”，项目级的parent适合放“项目特定版本”。
4.3 parent的dependencies和dependencyManagement的交互
一个常见的困惑：父POM的<dependencies>里写了依赖，子POM的<dependencyManagement>能不能改它的版本？
答案是不能。父POM的<dependencies>是实际引入，子POM的<dependencyManagement>只对“子POM自己声明的依赖”和“传递依赖”生效，管不到父POM已经引入的依赖。要改父POM引入的依赖版本，只能在子POM的<dependencies>里重新声明并写版本。
这也是为什么推荐父POM只放<dependencyManagement>：一旦父POM用了<dependencies>，子模块就失去了版本控制权。
5. 多模块项目的依赖治理实战
5.1 一套可落地的三层结构
经过多个项目的迭代，我总结出一套比较稳的组织方式，分三层：
第一层：公司级/组织级parent
只放dependencyManagement，声明公司统一的技术栈版本，比如日志、JSON、测试库、工具库。不放dependencies，不放build插件配置（除非是全公司强制的）。这一层的目标是“统一版本基线”。
第二层：项目级parent
继承公司级parent，放项目特定的dependencyManagement（覆盖或补充公司基线），放build的pluginManagement，放properties（如编译版本、编码）。这一层是项目依赖的“总控台”。
第三层：子模块
只声明自己实际需要的依赖，不写版本号。需要覆盖版本时，优先在项目级parent改，而不是在子模块里硬写。
这套结构的好处是：版本变更的影响范围清晰，公司级改动影响所有项目（需谨慎），项目级改动只影响本项目，子模块改动只影响自己。
5.2 用dependencyManagement统一传递依赖的坑
前面说dependencyManagement能覆盖传递依赖，但这里有个坑：它不能覆盖<optional>true</optional>的传递依赖，也不能覆盖被<exclusions>排除的依赖。
更隐蔽的坑是：如果两个库传递依赖了同一个库的不同大版本，而你在dependencyManagement里指定了一个版本，可能会导致其中一个库运行时报错。比如库A需要guava:18的某个API，库B需要guava:32，你统一到32，库A可能就崩了。
这种情况没有银弹。我的经验是：优先看能不能升级库A到兼容32的版本；如果不能，考虑用<exclusions>把库A的guava排除，然后单独给它引入一个shade过的版本。实在不行，只能接受版本分裂，用classloader隔离（比如OSGi或自定义类加载器），但这是最后手段。
5.3 版本属性集中管理
dependencyManagement里的版本号建议用<properties>集中管理：
<properties> <guava.version>32.1.2-jre</guava.version> <jackson.version>2.15.2</jackson.version> </properties> <dependencyManagement> <dependencies> <dependency> <groupId>com.google.guava</groupId> <artifactId>guava</artifactId> <version>${guava.version}</version> </dependency> </dependencies> </dependencyManagement>这样升级时只改属性值，而且属性名有语义，比裸版本号好维护。Spring Boot的parent就是这么干的，你可以打开spring-boot-dependencies的POM看看，里面全是${xxx.version}。
提示：属性名建议带
.version后缀，避免和dependencyManagement里的artifactId混淆。另外，属性是全局的，子模块也能引用，所以命名要加前缀避免冲突，比如project.guava.version。
6. 那些年踩过的版本冲突坑
6.1 依赖树里看到的版本和实际生效的不一样
mvn dependency:tree输出的版本，有时候和运行时实际加载的版本不一致。原因是dependency:tree默认显示的是“仲裁前”的版本，加-Dverbose才能看到被省略的版本。
更准的方式是用mvn dependency:tree -Dverbose -Dincludes=com.google.guava:guava，只看某个库的所有版本来源。输出里会标omitted for conflict，告诉你哪个版本被仲裁掉了。
如果还是不确定运行时用哪个版本，可以在代码里打印guava的Package.getImplementationVersion()，或者用mvn dependency:list看最终解析结果。
6.2 parent的relativePath在CI上失效
本地开发时relativePath默认../pom.xml能找到父POM，但CI上如果只checkout了子模块目录，父POM就不在上一级了。这时候要么在CI配置里checkout整个仓库，要么把父POM安装到本地仓库（mvn install -N），要么显式指定relativePath。
我遇到过一种情况：CI用了浅克隆，只拉了子模块的目录，结果mvn直接报找不到parent。解决办法是在CI脚本里先mvn install -N安装父POM，再构建子模块。
6.3 import scope的POM版本不匹配
用import导入Spring Boot的spring-boot-dependencies时，如果版本和spring-boot-maven-plugin的版本不一致，可能出现插件和依赖对不上的问题。建议用spring-boot-starter-parent作为parent，而不是手动import，因为parent里已经帮你对齐了插件版本。
如果非要用import（比如公司parent不能改），那就在properties里定义一个spring-boot.version，让import和plugin都用这个属性，保证一致。
6.4 子模块误写version导致管理失效
这是最常见的坑：明明在父POM的dependencyManagement里统一了版本，但某个子模块复制粘贴时带上了<version>，结果这个模块的版本就脱离了管控。升级父POM版本时，这个模块还是老版本，问题就来了。
排查方法：用mvn help:effective-pom看子模块的最终POM，搜索有没有多余的<version>。或者写个脚本扫描所有子POM的<dependencies>，检查有没有<version>标签。
注意：
<dependencyManagement>里的依赖可以写<version>，<dependencies>里的依赖不应该写（除非有意覆盖）。这个规则建议写进团队规范，用checkstyle或自定义脚本强制检查。
7. 几个容易混淆的边界问题
7.1 parent能不能替代dependencyManagement
不能。parent解决的是“继承配置”，dependencyManagement解决的是“版本声明”。你可以只用parent不用dependencyManagement，但那样每个子模块都得自己写版本；你也可以只用dependencyManagement不用parent（通过import），但那样就没有属性继承和插件管理。
实际项目里两者通常一起用：parent提供继承结构，dependencyManagement提供版本控制。
7.2 dependencyManagement能不能管插件版本
不能。插件版本由<build>下的<pluginManagement>管理，和<dependencyManagement>是两套体系。但它们的思路一样：pluginManagement声明插件版本，子模块的<plugins>里引用时不写版本。
<build> <pluginManagement> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-compiler-plugin</artifactId> <version>3.11.0</version> </plugin> </plugins> </pluginManagement> </build>7.3 BOM是什么，和dependencyManagement什么关系
BOM（Bill of Materials）就是一个只包含dependencyManagement的POM，通常用import引入。Spring Boot的spring-boot-dependencies就是一个BOM。BOM本身不引入任何依赖，只是提供一套版本清单。
自己也可以做BOM：建一个packaging为pom的模块，里面只写dependencyManagement，然后发布出去给其他项目import。这在多团队协作时很有用，比如基础架构团队维护一个BOM，业务团队import后统一技术栈版本。
7.4 版本仲裁的“最近优先”到底怎么算
Maven的依赖仲裁规则是：路径最短的优先，路径长度相同时先声明的优先。
“路径最短”指的是从根POM到该依赖的层级数。直接声明是第1层，传递依赖是第2层、第3层。所以直接声明的版本总是赢过传递依赖。
“先声明优先”指的是同一层级下，<dependencies>里写在前面的是赢家。这个规则在dependencyManagement介入时会失效，因为dependencyManagement是直接指定，不参与仲裁。
理解这个规则，就能解释为什么有时候调整<dependencies>的顺序会改变最终版本——虽然这种情况应该尽量避免，靠dependencyManagement来显式控制才是正道。
8. 我个人的几条实操建议
第一，父POM尽量只放dependencyManagement，不放dependencies。一旦放了dependencies，所有子模块都被迫引入，想排除都麻烦。如果确实有“所有模块都需要”的依赖，比如slf4j-api，可以考虑放，但要清楚它的影响范围。
第二，子模块的dependencies里不要写version。这是纪律问题，靠code review和脚本检查来保证。写了version就意味着脱离管控，升级时必然漏掉。
第三，版本属性统一用properties管理，命名加前缀。比如project.jackson.version，避免和import进来的BOM属性冲突。冲突时Maven的合并规则是“当前POM优先”，但属性冲突往往很隐蔽，不如一开始就加前缀。
第四，定期跑mvn dependency:tree -Dverbose检查冲突。尤其是引入新库之后，看看有没有意外的版本仲裁。CI里可以加一个步骤，把dependency:tree的输出存档，出问题时对比。
第五，升级父POM版本时，先在所有子模块跑一遍编译和测试。因为父POM的dependencyManagement改动会影响所有子模块，一个版本升级可能让某个模块的传递依赖变了，导致运行时才暴露的问题。本地全量构建是最基本的保障。
最后分享一个小技巧：如果某个子模块确实需要覆盖父POM的版本，优先在子模块的dependencyManagement里覆盖，而不是在dependencies里写version。这样至少版本声明是集中的，而且不会影响传递依赖的仲裁。虽然子模块的dependencyManagement会覆盖父POM，但它的作用范围仅限该子模块，比直接写version更可控。
