企业官网建设流程全解析

只要用 Maven 做过多模块项目，大概率都遇到过这么个鬼问题：明明在父pom.xml里用<dependencyManagement>把所有依赖的版本号都定义好了，子模块里也像模像样地写了<parent>标签，结果一执行mvn clean install，子模块要么报“找不到依赖”，要么直接给你拉一个默认版本甚至报错，版本号完全没继承过来。更气人的是，在 IDEA 的 Maven 面板里看，子模块的依赖树就是有问题的。

这个问题卡了我一个下午，网上搜了一堆资料，很多都只说了“要用 dependencyManagement”，但没解释清楚为什么有时候写了还是不生效。这篇文章我就把这个问题从头到尾拆一遍，先讲清楚 Maven 的依赖继承机制到底是怎么运作的，再给出一套可以直接落地的解决方案，最后把几个容易踩的坑也一并列出来，希望对正在被这个问题折磨的朋友有帮助。

1. 问题场景还原：子模块为什么拿不到父模块的版本号

先描述一下我遇到的具体情况，大家可以对号入座。项目的目录结构大致是这样：

my-project/ ├── pom.xml // 父模块 ├── my-common/ // 子模块1 │ └── pom.xml ├── my-service/ // 子模块2 │ └── pom.xml

父模块pom.xml的核心配置长这样：

<project> <groupId>com.example</groupId> <artifactId>my-project</artifactId> <version>1.0.0</version> <packaging>pom</packaging> <properties> <spring.boot.version>2.7.18</spring.boot.version> <guava.version>32.1.3-jre</guava.version> </properties> <dependencyManagement> <dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> <version>${spring.boot.version}</version> </dependency> <dependency> <groupId>com.google.guava</groupId> <artifactId>guava</artifactId> <version>${guava.version}</version> </dependency> </dependencies> </dependencyManagement> </project>

子模块my-common/pom.xml的配置长这样：

<project> <parent> <groupId>com.example</groupId> <artifactId>my-project</artifactId> <version>1.0.0</version> </parent> <artifactId>my-common</artifactId> <dependencies> <dependency> <groupId>com.google.guava</groupId> <artifactId>guava</artifactId> </dependency> </dependencies> </project>

这里就有意思了：我在子模块里引入guava时，故意没有写<version>，因为按照 Maven 的继承机制，父模块的dependencyManagement应该会帮我管好版本。但实际执行mvn clean install时，报错信息非常直白：

[ERROR] 'dependencies.dependency.version' for com.google.guava:guava:jar is missing.

翻译过来就是：guava 这个依赖缺少版本号。

这就是典型的“子模块依赖继承不到父模块依赖定义的版本号”问题。接下来我从原理层面好好讲一下，为什么会出现这种情况。

2. 核心原理拆解：dependencyManagement 与 dependencies 的区别

很多刚接触 Maven 的开发者会把父模块里的<dependencyManagement>和<dependencies>弄混，这两个东西看起来都是声明依赖，但作用机制完全不一样。

2.1 dependencyManagement 只是“锁定版本”，不是“引入依赖”

<dependencyManagement>的核心作用是统一管理依赖版本号，它本身不会给当前模块引入任何依赖。你可以把它理解成一份“版本约定清单”：

清单上写明了某个groupId:artifactId应该用哪个版本，但只有子模块（或自身）真正在<dependencies>里声明了这个依赖，这份清单才会生效。

这份清单的生效方式是“向下传递”，传递的不仅仅是版本号，还包括<scope>、<exclusions>等依赖属性。也就是说，如果子模块在<dependencies>里声明了guava但不写版本号，Maven 会去父模块的dependencyManagement里找有没有对应的条目，找到就自动补全版本；找不到就报错。

2.2 dependencies 是“真实引入”，子模块默认继承

父模块里的<dependencies>就不同了，它是实际依赖声明。凡是在父模块<dependencies>里写明的依赖，子模块会无条件继承，不需要子模块再主动声明。这也就是为什么有的项目把公共依赖放在父模块的<dependencies>里，想省去每个子模块重复配置的麻烦。

但这样做有个问题：如果父模块的<dependencies>条目很多，所有子模块都会被迫引入这些依赖，哪怕某些依赖子模块根本用不到。这样会导致项目的依赖体积膨胀、构建变慢，严重时还会引发依赖冲突。

2.3 两个机制的分工逻辑

简单总结一句话：

• 用dependencyManagement：只约定版本，子模块按需声明，灵活度最高。
• 用dependencies：直接传递依赖，子模块必须接受，省事但不够灵活。

实际项目里最推荐的还是父模块用 dependencyManagement 管版本，子模块按需声明依赖，这也是 Spring Boot 官方父 POM 的做法。

3. 问题根因分析：为什么代码看着没问题却不生效

我当初也郁闷，明明父模块里dependencyManagement写了，子模块也写了<parent>，怎么就是继承不到？排查了一下午，归纳下来主要是这四种原因。

3.1 原因一：父模块的 packaging 不是 pom

这个是新手最容易踩的坑。父模块的<packaging>如果没单独设置，Maven 默认是jar。但作为多模块项目的父模块，它本身是不产出代码的，它的作用只是聚合子模块并管理公共配置，所以<packaging>必须显式声明为pom。

<packaging>pom</packaging>

如果漏掉这行，父模块会被当成普通 jar 模块，Maven 的依赖管理传递机制就不会按期望的方式工作。这个问题排查起来也非常隐蔽，因为 IDEA 里不一定有特别明显的报错提示。

3.2 原因二：parent 标签的 relativePath 写错或缺失

子模块里的<parent>标签通常会这样写：

<parent> <groupId>com.example</groupId> <artifactId>my-project</artifactId> <version>1.0.0</version> </parent>

这里有个隐藏属性<relativePath>，默认值是../pom.xml。也就是说，Maven 默认会去当前子模块的上一级目录找父 POM。如果项目结构不是标准的“子模块直接在父模块目录下”，比如子模块在二层目录里，这个默认值就找不到父 POM 了。

my-project/ ├── pom.xml └── modules/ └── my-service/ └── pom.xml

这种情况下，Maven 找不到../pom.xml，就会去本地仓库或远程仓库找父 POM。如果没有安装过父 POM，就会报错或者继承不到任何配置。解决办法是显式指定relativePath：

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

3.3 原因三：父 POM 没有安装到本地仓库

父 POM 的依赖管理要想在子模块中生效，前提是父 POM 已经被 Maven 解析到。如果项目还没有执行过mvn install，或者父 POM 没有发布到远程仓库，子模块在单独构建时就可能拿不到父 POM 的配置。

尤其是当你直接进入子模块目录执行mvn clean install时，Maven 会先尝试从本地仓库找父 POM。找不到就报错。解决办法是先在父模块目录下执行一次：

mvn clean install -N

这里的-N表示--non-recursive，只构建父模块本身，不递归构建子模块。这样父 POM 就会被安装到本地仓库，后续子模块构建时就能正常解析到父 POM 了。

3.4 原因四：子模块里重复写了 version，但写错了位置

还有一个低级错误：在子模块的<dependencyManagement>里重复声明了相同依赖，但版本号写的是别的值，或者干脆覆盖了父模块的版本定义。Maven 的规则是子模块里的声明优先于父模块，所以一旦子模块里自己写了版本号，父模块的版本管理就“失效”了，这个不算 Bug，而是 Maven 的设计。

但问题在于：如果有多个子模块各自定义版本号，比如 A 模块用 1.0，B 模块用 1.2，整体项目就失去了版本统一管理的意义，后续升级版本会非常痛苦。所以排查时也看一眼子模块里有没有重复的依赖声明。

4. 解决方案实操：三种方式对照讲解

弄清楚了原理和根因，解决起来就有针对性了。我分三种情况给出解决方案，按推荐程度排序。

4.1 方案一：正确配置 dependencyManagement（推荐）

这是最标准的做法。父模块里用dependencyManagement统一管版本，子模块只声明groupId和artifactId。

父模块 POM 完整示例：

<project> <modelVersion>4.0.0</modelVersion> <groupId>com.example</groupId> <artifactId>my-project</artifactId> <version>1.0.0</version> <packaging>pom</packaging> <modules> <module>my-common</module> <module>my-service</module> </modules> <properties> <spring.boot.version>2.7.18</spring.boot.version> <guava.version>32.1.3-jre</guava.version> <lombok.version>1.18.30</lombok.version> </properties> <dependencyManagement> <dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> <version>${spring.boot.version}</version> </dependency> <dependency> <groupId>com.google.guava</groupId> <artifactId>guava</artifactId> <version>${guava.version}</version> </dependency> <dependency> <groupId>org.projectlombok</groupId> <artifactId>lombok</artifactId> <version>${lombok.version}</version> </dependency> </dependencies> </dependencyManagement> </project>

子模块 POM 完整示例：

<project> <modelVersion>4.0.0</modelVersion> <parent> <groupId>com.example</groupId> <artifactId>my-project</artifactId> <version>1.0.0</version> <relativePath>../pom.xml</relativePath> </parent> <artifactId>my-common</artifactId> <dependencies> <dependency> <groupId>com.google.guava</groupId> <artifactId>guava</artifactId> </dependency> </dependencies> </project>

这套配置的关键点：

• 父模块必须是<packaging>pom</packaging>。
• 子模块的<parent>标签里的groupId、artifactId、version必须和父模块完全一致。
• relativePath建议显式写出来，指向父 POM 的路径。
• 子模块的依赖只写groupId和artifactId，不写version。

4.2 方案二：用父模块的 dependencies 直接传递（不推荐用于大规模项目）

如果你的子模块确实需要把父模块的所有依赖都继承下来，可以在父模块的<dependencies>里直接声明。

<dependencies> <dependency> <groupId>com.google.guava</groupId> <artifactId>guava</artifactId> <version>32.1.3-jre</version> </dependency> </dependencies>

这样任何子模块都会自动引入 guava，不需要额外声明。问题是依赖全部强制传递，子模块无法按需选择。如果某个子模块根本不需要 guava，它也无法避免这个依赖被加载进 classpath。项目规模小还好，规模大了以后依赖树会非常臃肿，而且出现版本冲突时排查成本很高。

所以我的建议是：如果项目只有两三个模块，图省事可以用这种方式；只要模块数量上来，还是老老实实用 dependencyManagement。前者省了配置但埋了雷，后者多写几行但边界清晰。

4.3 方案三：直接用 BOM 统一管理版本

这个方案没有前两个那么通用，但遇到“不想用父 POM 继承”的场景时特别好用。BOM（Bill of Materials）本身就是一个独立的 POM 文件，里面只包含dependencyManagement，不包含其他逻辑。团队可以把它当做一个独立的“版本清单”依赖来引用。

在子模块的 POM 里这样写：

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

BOM 的好处是，你不一定非要让子模块通过<parent>继承父模块，而是可以只通过引入 BOM 来获得版本管理能力。Spring Boot 的spring-boot-dependencies就是这样的结构。

但注意，BOM 方案并不意味着可以完全不用<parent>。如果你想省去重复配置<groupId>、<version>，还是要有一个父 POM 来承载这些公共信息。所以更常见的组合是：父 POM 里用<parent>继承 Spring Boot 的官方父 POM，再引入自定义 BOM 或者直接在 dependencyManagement 里声明自己的版本清单。

5. 实操验证过程：从报错到正常构建的完整记录

理论讲完了，按惯例走一遍完整的验证过程，方便大家对照操作。

5.1 第一步：检查父 POM 配置

打开父模块的pom.xml，确认这些关键点：

• <packaging>是否为pom。
• <modules>是否包含所有子模块。
• <dependencyManagement>是否声明了需要统一管理的依赖。

可以直接在根目录下执行这个命令，验证父 POM 能否被正确解析：

mvn -N validate

如果输出里有BUILD SUCCESS，说明父 POM 本身没有问题。

5.2 第二步：检查子模块的 parent 配置

逐个打开子模块的pom.xml，确认：

• <parent>的groupId、artifactId、version是否和父模块匹配。
• <relativePath>是否指向正确的父 POM 路径。

标准的多模块目录结构是这样的：

my-project/ ├── pom.xml ├── my-common/ │ └── pom.xml └── my-service/ └── pom.xml

那么my-common/pom.xml里的relativePath应该是../pom.xml。如果你的项目目录不同，相应调整。

5.3 第三步：先安装父 POM，再构建子模块

这是很多人忽略的一步。强烈建议先在根目录执行：

mvn clean install -N

这一步会把父 POM 安装到本地仓库。之后无论是在 IDEA 里操作还是命令行构建子模块，父 POM 都能被正确解析。

然后回到项目根目录，执行完整的构建：

mvn clean install

看到BUILD SUCCESS后，再去 IDEA 的 Maven 面板刷新一下，这时子模块的依赖就应该能正常引入了。验证依赖是否正确的命令是：

mvn dependency:tree

重点看对应依赖的版本号是否是父模块dependencyManagement里定义的版本。比如我预期看到：

[INFO] +- com.google.guava:guava:jar:32.1.3-jre:compile

如果版本号对得上，说明继承机制已经生效。

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

这部分把实际调试过程中容易遇到的问题整理成了速查表，并按实际踩坑频率排了序。直接对照排查，比自己瞎猜快很多。

6.1 排查技巧一：用 mvn help:effective-pom 查看真实生效的 POM

如果写了半天还是不确定到底哪个配置生效了，最直接的办法是查看合并后的“有效 POM”。Maven 在构建时会把父 POM 和子模块 POM 合并成一个完整的有效 POM，这个合并过程对我们来说是黑盒，只有结果可见。

在子模块目录下执行：

mvn help:effective-pom

Maven 会把所有继承来的配置合并后输出到控制台，这样就能直观地看到dependencyManagement是否被正确继承、版本号有没有生效。这个命令是我排查 Maven 继承问题最常用的手段，比反复读配置文件有效得多。

6.2 排查技巧二：使用 IDEA 的 Maven 面板定位依赖归属

在 IDEA 右侧的 Maven 面板中，展开对应的子模块，找到“Dependencies”节点，可以看到该模块最终引入的所有依赖及其版本号。如果你发现某个依赖的版本号和预期不符，可以直接在这个面板里右键 -> “Jump to source”，查看这个版本的依赖是从哪里来的。IDEA 还会用红色波浪线标注冲突的依赖，非常直观。

我一般会把 IDEA 的“Reload All Maven Projects”按钮当成第一排查动作，虽然听起来很基础，但很多问题在刷新后都会自然解决，因为父 POM 更新过了，子模块缓存还没跟上。

7. 几个容易忽略的细节经验

最后分享几个在多次实操中总结出来的经验，这些细节普通文档里可能不会特意提，但直接影响成功率。

7.1 版本号统一用 properties 管理

在父 POM 里用<properties>统一声明版本号，然后在<dependencyManagement>里通过${xxx.version}引用。版本升级时只改一个地方，不用在多个依赖条目里来回调整。这个看起来只是代码整洁问题，其实长期维护时差距很明显。

<properties> <guava.version>32.1.3-jre</guava.version> </properties> <dependencyManagement> <dependencies> <dependency> <groupId>com.google.guava</groupId> <artifactId>guava</artifactId> <version>${guava.version}</version> </dependency> </dependencies> </dependencyManagement>

7.2 不要为了省事把所有依赖塞进父 POM 的 dependencies

前面提到过，父 POM 的<dependencies>会被所有子模块无条件继承。如果 A 模块只用到了数据库连接池，B 模块只用到了 JSON 解析库，但你把这些都塞进了父 POM，A 和 B 都会被强制引入它们不需要的依赖。这种隐形的依赖膨胀，短时间内不会有感觉，但项目越做越大以后，打包体积、启动速度、依赖冲突问题都会逐渐冒出来。

正确的姿势是：父 POM 只管版本（dependencyManagement），子模块按需引入（dependencies）。只有像lombok这种几乎所有模块都会用到的依赖，才考虑放到父 POM 的dependencies里。

7.3 -N 参数是个好东西

mvn clean install -N这个命令，-N是--non-recursive的简写，意思是只处理当前模块，不递归处理子模块。在构建父 POM 时加上这个参数，既能快速把父 POM 安装到本地仓库，又不会把子模块也一并构建了，省时间也省心。

第一次构建项目时，我习惯先跑一遍mvn clean install -N安装父 POM，然后再跑mvn clean install全量构建。这样层级清晰，出问题时也容易定位。

8. 写在最后的实操体会

Maven 的依赖继承机制用熟了以后，回头看这个问题其实并不复杂，核心就是搞懂一件事：dependencyManagement管版本，dependencies管引入，两者分工不同，不能混淆。绝大多数“继承不到版本号”的问题，归根结底都是这几个原因里的一个：父 POM 的 packaging 不是 pom、parent 相对路径不对、父 POM 没有 install 到本地仓库、或者子模块自己重复声明了依赖。

我个人在日常项目中的标准做法是：父 POM 里只放<dependencyManagement>和<properties>，所有子模块按需在<dependencies>里声明依赖，版本号一律不给。配合mvn help:effective-pom和 IDEA 的 Maven 面板做校验，基本不会再被这个问题卡住。另外，每次修改父 POM 后，一定要记得在根目录执行一次mvn clean install -N，否则 IDEA 里即使点了刷新，也可能用的还是旧的父 POM 缓存。

如果项目里遇到类似问题，别急着改代码，先按上面的排查顺序走一遍，大概率五分钟内就能定位到原因。