Maven多模块依赖管理：parent与dependencyManagement实战指南

1. 从一次依赖冲突说起：为什么必须搞懂parent与dependencyManagement

如果你维护过稍微大一点的多模块项目，大概率遇到过这种场景：A模块引入了某个工具库的1.2版本，B模块引入了同一个库的1.5版本，最后打包上线，运行时莫名其妙报NoSuchMethodError。排查半天，发现是依赖树里同一个坐标出现了两个版本，Maven按“最近优先”策略选了一个，结果选中的那个恰好缺了某个方法。这类问题的根源，往往就是版本管理没做好，而parent和dependencyManagement这两个标签，正是解决这类问题的核心手段。

这篇文章面向的是已经会用Maven跑clean install、但还没系统梳理过多模块依赖管理的开发者。我会把parent继承机制和dependencyManagement版本锁定机制拆开讲透，包括它们各自解决什么问题、怎么配合使用、有哪些容易踩的坑。读完你应该能做到：自己搭一套多模块工程，让所有子模块的依赖版本统一收口，改一处版本号全工程生效，同时不引入多余的依赖。

需要先明确一个概念：parent和dependencyManagement不是一回事，但经常一起出现。parent解决的是“配置继承”问题——子模块可以继承父工程的groupId、version、properties、dependencies、dependencyManagement、插件配置等。dependencyManagement解决的是“版本声明”问题——它只声明依赖的版本和scope，不实际引入依赖，子模块需要用到某个依赖时，自己写groupId和artifactId即可，版本从父工程的dependencyManagement里取。两者配合，才能实现“版本统一管理、依赖按需引入”。

很多人第一次接触这两个标签，是在公司现成的工程模板里，照着抄了一遍，能跑起来就不管了。但一旦要新增模块、升级依赖、或者排查冲突，就会露怯。所以下面我不只讲“怎么写”，更讲“为什么这么设计”。

2. parent标签：继承机制到底继承了什么

2.1 parent的两种形态：聚合与继承的区别

初学者最容易混淆的一点，是把<modules>聚合和<parent>继承当成一回事。实际上这是两个独立的概念，只是经常写在同一个pom里。

聚合（aggregation）是通过父工程的<modules>标签把多个子模块组织在一起，执行父工程的构建命令时，Maven会按顺序构建所有子模块。聚合关系是“父工程知道有哪些子模块”，子模块不需要知道父工程的存在。

继承（inheritance）是通过子模块的<parent>标签声明“我的父工程是谁”，从而继承父工程的配置。继承关系是“子模块知道自己的父工程”，父工程不需要知道有哪些子模块。

一个典型的父pom通常两者都有：

<project> <groupId>com.example.demo</groupId> <artifactId>demo-parent</artifactId> <version>1.0.0</version> <packaging>pom</packaging> <modules> <module>demo-common</module> <module>demo-service</module> <module>demo-web</module> </modules> </project>

而子模块的pom这样写：

<project> <parent> <groupId>com.example.demo</groupId> <artifactId>demo-parent</artifactId> <version>1.0.0</version> <relativePath>../pom.xml</relativePath> </parent> <artifactId>demo-common</artifactId> </project>

注意子模块里没有写groupId和version，因为它们从父工程继承了。relativePath指向父pom的相对路径，默认值是../pom.xml，如果父pom不在上级目录，必须显式指定，否则Maven会去本地仓库找，找不到就报错。

提示：relativePath这个坑很隐蔽。如果你把父pom放在了一个非标准位置，比如../parent/pom.xml，却忘了改relativePath，Maven会先去本地仓库找父pom，找不到才回退到relativePath。有时候本地仓库恰好有旧版本，就会用错父pom，导致配置不生效。建议显式写上relativePath，并且用<relativePath/>空标签可以强制Maven只从仓库找父pom，不走相对路径。

2.2 哪些配置会被继承，哪些不会

继承不是无条件的。父pom里的大部分配置会被子模块继承，但有几类例外需要特别注意。

会被继承的包括：groupId、version、properties、dependencies、dependencyManagement、build下的插件配置、repositories、pluginRepositories、distributionManagement等。

不会被继承或行为特殊的有：artifactId（每个模块必须自己声明）、name、description、packaging（子模块默认jar，除非显式声明）、modules（聚合关系不继承）、parent本身（子模块的parent不会传递给孙模块，除非孙模块自己声明）。

这里有个容易忽略的点：dependencies里的依赖会被所有子模块无条件继承。也就是说，如果你在父pom的<dependencies>里写了一个spring-boot-starter-web，那么所有子模块都会自动引入它，哪怕某个子模块只是个纯工具类库，根本不需要web相关的东西。这就是为什么最佳实践是：父pom里尽量只放dependencyManagement，把实际依赖的引入交给子模块自己决定。

2.3 parent的层级链与super pom

Maven的继承是可以多层的：A是B的父工程，B是C的父工程，C可以继承到A的配置。这条链最终会指向Maven内置的super pom，它定义了所有pom的默认值，比如默认的groupId是org.apache.maven、默认的packaging是jar、默认的中央仓库地址等。

理解这条链的意义在于：当你在子模块里找不到某个配置的来源时，可以沿着parent链一路往上查，最终一定能找到。排查依赖版本问题时，mvn help:effective-pom命令可以打印出合并后的完整pom，非常有用。

mvn help:effective-pom -Doutput=effective-pom.xml

这条命令会把当前模块继承合并后的最终pom输出到文件，你可以直接搜索某个依赖的版本，看它到底是从哪里来的。

3. dependencyManagement：只声明不引入的版本锁

3.1 它和dependencies的本质区别

dependencyManagement最核心的一句话：它只管理版本，不引入依赖。这句话听起来简单，但很多人第一次用会犯迷糊——在父pom的dependencyManagement里写了某个依赖，子模块里不写，结果发现依赖根本没进来。

对比一下就很清楚：

<!-- 父pom --> <dependencyManagement> <dependencies> <dependency> <groupId>com.google.guava</groupId> <artifactId>guava</artifactId> <version>32.1.3-jre</version> </dependency> </dependencies> </dependencyManagement>

<!-- 子模块：这样写才会真正引入guava，版本从父pom取 --> <dependencies> <dependency> <groupId>com.google.guava</groupId> <artifactId>guava</artifactId> </dependency> </dependencies>

子模块里不写<version>，Maven会去父工程的dependencyManagement里找匹配的groupId+artifactId，找到就用那个版本。如果子模块自己写了<version>，则以子模块的为准，父工程的声明被覆盖。

这个设计的好处是：版本号集中在一处维护，子模块只关心“我要用哪些依赖”，不关心“用哪个版本”。升级时只改父pom一处，所有子模块同步生效。

3.2 版本仲裁规则：谁说了算

当同一个依赖在多个地方出现版本声明时，Maven有一套仲裁规则，优先级从高到低大致是：

1. 子模块dependencies里显式写的version最高。
2. 父工程dependencyManagement里的版本次之。
3. 如果依赖是通过传递依赖进来的，则按“最近优先”原则，路径短的优先；路径长度相同时，先声明的优先。

这里有个细节：dependencyManagement的版本声明优先级高于传递依赖。也就是说，如果A依赖B，B传递依赖了guava 30.0，而你在父pom的dependencyManagement里声明了guava 32.1.3，那么最终生效的是32.1.3。这正是dependencyManagement能用来统一版本的原因——它可以覆盖传递依赖带来的版本。

但要注意，dependencyManagement不能强制降级一个已经在子模块dependencies里显式声明了版本的依赖。如果子模块自己写了版本，父工程管不了。

3.3 import scope：引入外部BOM

dependencyManagement还有一个高级用法：importscope。它允许你把另一个pom的dependencyManagement配置导入进来，常用于引入官方提供的BOM（Bill of Materials）。

<dependencyManagement> <dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-dependencies</artifactId> <version>3.2.0</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement>

这样写之后，Spring Boot官方BOM里声明的所有依赖版本都可以直接使用，子模块引入spring相关依赖时不用写版本。importscope的依赖必须是pom类型，且只对dependencyManagement生效，写在普通dependencies里没有意义。

注意：importscope的导入顺序有讲究。如果同时导入了多个BOM，后导入的会覆盖先导入的同名依赖版本。另外，当前pom自己的dependencyManagement声明优先级高于导入的BOM，所以你可以用本地声明覆盖BOM里的版本。

4. 实战：搭一套多模块工程的依赖管理体系

4.1 工程结构设计

假设我们要做一个电商后端系统，拆成四个模块：mall-common（工具类）、mall-dao（数据访问）、mall-service（业务逻辑）、mall-web（接口层）。父工程mall-parent负责统一管理版本。

目录结构如下：

mall-parent/ ├── pom.xml ├── mall-common/ │ └── pom.xml ├── mall-dao/ │ └── pom.xml ├── mall-service/ │ └── pom.xml └── mall-web/ └── pom.xml

父pom的packaging必须是pom，因为它不产出jar，只做聚合和配置管理。

4.2 父pom的完整配置

<project xmlns="http://maven.apache.org/POM/4.0.0"> <modelVersion>4.0.0</modelVersion> <groupId>com.example.mall</groupId> <artifactId>mall-parent</artifactId> <version>1.0.0</version> <packaging>pom</packaging> <modules> <module>mall-common</module> <module>mall-dao</module> <module>mall-service</module> <module>mall-web</module> </modules> <properties> <java.version>17</java.version> <maven.compiler.source>17</maven.compiler.source> <maven.compiler.target>17</maven.compiler.target> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> <spring-boot.version>3.2.0</spring-boot.version> <guava.version>32.1.3-jre</guava.version> <mybatis-plus.version>3.5.5</mybatis-plus.version> </properties> <dependencyManagement> <dependencies> <!-- 导入Spring Boot BOM --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-dependencies</artifactId> <version>${spring-boot.version}</version> <type>pom</type> <scope>import</scope> </dependency> <!-- 内部模块版本统一管理 --> <dependency> <groupId>com.example.mall</groupId> <artifactId>mall-common</artifactId> <version>${project.version}</version> </dependency> <dependency> <groupId>com.example.mall</groupId> <artifactId>mall-dao</artifactId> <version>${project.version}</version> </dependency> <dependency> <groupId>com.example.mall</groupId> <artifactId>mall-service</artifactId> <version>${project.version}</version> </dependency> <!-- 第三方依赖版本 --> <dependency> <groupId>com.google.guava</groupId> <artifactId>guava</artifactId> <version>${guava.version}</version> </dependency> <dependency> <groupId>com.baomidou</groupId> <artifactId>mybatis-plus-boot-starter</artifactId> <version>${mybatis-plus.version}</version> </dependency> </dependencies> </dependencyManagement> <build> <pluginManagement> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-compiler-plugin</artifactId> <version>3.11.0</version> <configuration> <source>${java.version}</source> <target>${java.version}</target> </configuration> </plugin> </plugins> </pluginManagement> </build> </project>

这里有几个设计决策值得说明。第一，用properties集中定义版本号，而不是把版本号硬编码在dependencyManagement里，这样升级时改一处即可。第二，内部模块的版本用${project.version}，保证和父工程版本一致，避免手动维护。第三，pluginManagement和dependencyManagement是同样的思路——只声明插件配置，不实际执行，子模块需要时自己声明插件。

4.3 子模块的依赖声明

以mall-service为例，它的pom这样写：

<project> <parent> <groupId>com.example.mall</groupId> <artifactId>mall-parent</artifactId> <version>1.0.0</version> <relativePath>../pom.xml</relativePath> </parent> <artifactId>mall-service</artifactId> <dependencies> <dependency> <groupId>com.example.mall</groupId> <artifactId>mall-dao</artifactId> </dependency> <dependency> <groupId>com.example.mall</groupId> <artifactId>mall-common</artifactId> </dependency> <dependency> <groupId>com.google.guava</groupId> <artifactId>guava</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter</artifactId> </dependency> </dependencies> </project>

所有依赖都不写版本，版本从父工程的dependencyManagement取。mall-dao和mall-common的版本是${project.version}，也就是1.0.0。guava是32.1.3-jre。spring-boot-starter的版本来自导入的Spring Boot BOM。

这样做的效果是：如果要把guava升级到33.0，只需要改父pom的guava.version属性，所有子模块同步生效。如果要把整个项目版本从1.0.0升到2.0.0，改父pom的version，内部模块的依赖版本自动跟着变。

4.4 验证依赖树

配置写完后，一定要验证依赖树是否符合预期。用mvn dependency:tree命令：

mvn dependency:tree -pl mall-service

-pl参数指定只查看某个模块。输出会显示完整的依赖树，你可以检查guava的版本是不是32.1.3-jre，有没有出现意外的重复依赖。

如果发现某个依赖出现了多个版本，可以用mvn dependency:tree -Dverbose查看被省略的冲突版本，Maven会标注omitted for conflict。

mvn dependency:tree -Dverbose -pl mall-service

输出里会看到类似这样的行：

[INFO] +- com.google.guava:guava:jar:32.1.3-jre:compile [INFO] | \- (com.google.guava:guava:jar:30.0-jre:compile - omitted for conflict with 32.1.3-jre)

这说明30.0版本被32.1.3覆盖了，符合预期。

5. 常见问题与排查技巧实录

5.1 子模块版本不生效的几种原因

问题一：relativePath写错，Maven用了本地仓库的旧父pom。表现是改了父pom的版本号，子模块构建时还是用旧版本。排查方法是执行mvn help:effective-pom，看合并后的pom里版本号是多少。解决方法是显式写对relativePath，或者用<relativePath/>强制从仓库找。

问题二：子模块自己写了version，覆盖了父工程的管理。这种情况dependencyManagement管不了，需要把子模块里的version删掉。排查时搜索子模块pom里所有<version>标签，确认哪些是必要的（比如parent里的version必须写）。

问题三：dependencyManagement里声明的groupId+artifactId和子模块引入的不完全匹配。比如父工程声明的是com.google.guava:guava，子模块写的是com.google.guava:guava-jre，两者不匹配，版本管理不生效。排查时仔细核对坐标。

问题四：importscope的BOM导入顺序问题。如果导入了多个BOM，后导入的覆盖先导入的。如果你发现某个依赖版本不是预期的，检查是不是被后面的BOM覆盖了。

5.2 依赖冲突排查速查表

5.3 几个容易踩的坑

坑一：在父pom的dependencies里写依赖。这是新手最常见的错误。父pom的dependencies会被所有子模块继承，导致不需要的依赖被引入。正确做法是只在父pom写dependencyManagement，实际依赖由子模块自己声明。

坑二：dependencyManagement里声明了依赖，子模块忘了引入。因为dependencyManagement不引入依赖，子模块必须自己写dependencies。如果发现某个依赖没进来，先检查子模块有没有声明。

坑三：scope的管理。dependencyManagement里可以声明scope，子模块引入时会继承这个scope。比如父工程声明<scope>test</scope>，子模块引入时不写scope，就默认是test。如果子模块想改成compile，需要显式覆盖。

坑四：多级继承时版本被中间层覆盖。如果A是B的父，B是C的父，A的dependencyManagement声明了guava 32.1.3，B的dependencyManagement声明了guava 30.0，那么C继承到的是30.0，因为B的声明更近。排查时要沿着parent链逐层检查。

坑五：optional和provided的传递性。optional为true的依赖不会传递给下游模块，provided的依赖也不会传递。如果你在父工程声明了某个依赖为optional，子模块引入时要注意它不会自动传递。

实操心得：我习惯在父pom里加一个<properties>块，把所有第三方依赖的版本号都定义成属性，然后在dependencyManagement里用${xxx.version}引用。这样升级时只需要改属性值，不用在dependencyManagement里翻找。另外，我会定期执行mvn versions:display-dependency-updates检查有没有新版本可用，但不会盲目升级，而是先看release notes确认没有破坏性变更。

6. 进阶：dependencyManagement在微服务场景下的用法

6.1 统一公司内部技术栈版本

在微服务架构下，通常有几十个服务，每个服务是一个独立的Maven工程。如果每个工程各自管理依赖版本，很容易出现A服务用Spring Boot 3.1、B服务用3.2的情况，导致公共库不兼容。

解决方案是做一个公司级的bom工程，只包含dependencyManagement，不包含任何代码。所有业务服务的父工程都继承这个bom，或者通过importscope导入。这样技术栈版本统一收口，升级时改bom一处，所有服务同步。

<!-- 公司级bom --> <project> <groupId>com.example</groupId> <artifactId>company-bom</artifactId> <version>1.0.0</version> <packaging>pom</packaging> <dependencyManagement> <dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-dependencies</artifactId> <version>3.2.0</version> <type>pom</type> <scope>import</scope> </dependency> <!-- 其他公共依赖版本 --> </dependencies> </dependencyManagement> </project>

业务服务的父工程这样导入：

<dependencyManagement> <dependencies> <dependency> <groupId>com.example</groupId> <artifactId>company-bom</artifactId> <version>1.0.0</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement>

6.2 多环境版本差异管理

有时候不同环境需要用不同版本的依赖，比如测试环境用某个快照版本，生产环境用稳定版。可以用Maven的profile配合properties实现：

<profiles> <profile> <id>dev</id> <properties> <guava.version>32.1.3-jre</guava.version> </properties> <activation> <activeByDefault>true</activeByDefault> </activation> </profile> <profile> <id>prod</id> <properties> <guava.version>32.1.3-jre</guava.version> </properties> </profile> </profiles>

构建时用-Pprod激活对应profile，版本号自动切换。不过这种做法要谨慎，多环境版本不一致容易导致“测试通过、生产报错”的问题，建议只在确实必要时使用。

6.3 与Gradle的对比思考

如果你同时接触过Gradle，会发现Gradle用platform和constraints实现类似功能。Maven的dependencyManagement相当于Gradle的platform，importscope相当于platform依赖。两者思路一致：把版本声明和依赖引入分离。理解了这个设计理念，换到Gradle也能快速上手。

Maven的优势是约定强、结构固定，适合团队协作；Gradle灵活但需要更多自律。在依赖管理这件事上，Maven的parent+dependencyManagement组合已经足够覆盖绝大多数场景，没必要为了灵活而牺牲可维护性。

7. 我个人的几条实操建议

第一，父pom只做三件事：聚合模块、声明dependencyManagement、配置pluginManagement。不要在父pom的dependencies里写任何实际依赖，这是保持工程干净的关键。

第二，所有版本号都定义在properties里，dependencyManagement只引用属性。这样升级时一目了然，也方便用脚本批量替换。

第三，内部模块的版本统一用${project.version}，不要手动写死。这样发布新版本时，所有内部依赖自动对齐。

第四，定期执行mvn dependency:tree和mvn help:effective-pom，确认依赖树和最终配置符合预期。不要等到运行时报错才去排查。

第五，如果团队有多个项目，考虑抽一个公司级bom，用importscope引入。这样技术栈版本统一，新项目接入成本低。

第六，遇到依赖冲突时，优先用dependencyManagement锁定版本，而不是用exclusions排除依赖。排除依赖会让依赖树变得难以维护，锁定版本更可控。

最后分享一个排查小技巧：当你怀疑某个依赖的版本不对时，在子模块目录下执行mvn dependency:tree -Dincludes=groupId:artifactId，只显示指定依赖的路径，输出更清晰。比如mvn dependency:tree -Dincludes=com.google.guava:guava，能直接看到guava是从哪条路径进来的、最终选中了哪个版本。这个命令我用了好几年，排查冲突时比看完整依赖树高效得多。