Maven 的 pom.xml 是项目构建的核心配置文件，标签非常多。为了让你清晰掌握，我将它们分为 五大核心板块 ，并配合 详细示例 和 避坑指南。
📂 一、项目坐标与基础信息 (Project Coordinates)
作用：定义项目的"身份证"，全球唯一标识。
表格
| 标签 | 必填 | 含义 | 示例 |
|---|---|---|---|
<modelVersion> |
✅ | POM 模型版本，固定为 4.0.0 |
4.0.0 |
<groupId> |
✅ | 组织/公司 ID (反向域名) | com.alipay.sofa |
<artifactId> |
✅ | 项目/模块名称 | sofaboot-core |
<version> |
✅ | 版本号 (语义化版本) | 3.10.5 |
<packaging> |
❌ | 打包方式 (默认 jar) | jar, war, pom |
<name> |
❌ | 项目展示名称 | SOFABoot Core |
<description> |
❌ | 项目描述 | Core module of SOFABoot |
<url> |
❌ | 项目主页 URL | https://www.sofastack.com |
💡 示例：
<project>
<modelVersion>4.0.0</modelVersion>
<!-- 坐标三要素 -->
<groupId>com.example</groupId>
<artifactId>my-shop-order</artifactId>
<version>1.0.0-SNAPSHOT</version>
<!-- 打包方式：如果是父工程或 BOM，这里必须是 pom -->
<packaging>jar</packaging>
<name>My Shop Order Service</name>
<description>Order management module for My Shop</description>
</project>🧩 二、依赖管理 (Dependency Management)
作用 ：控制依赖的版本 和传递性，解决冲突。这是你之前问题的核心区域。
1. <dependencyManagement> (版本字典)
-
特点 ：只定义版本，不下载 Jar 包。子模块引用时可省略版本号。
-
场景：父工程统一管控所有子模块的依赖版本。
org.springframework.boot spring-boot-dependencies 2.7.18 pom import <!-- 手动锁定某个特定依赖的版本 --> <dependency> <groupId>com.google.guava</groupId> <artifactId>guava</artifactId> <version>32.1.3-jre</version> </dependency> </dependencies>
2. <dependencies> (实际依赖)
-
特点 ：真正下载 Jar 包，加入 Classpath。
-
场景：当前模块实际需要用到的库。
org.springframework.boot spring-boot-starter-web <!-- 2. 带有特殊配置的依赖 --> <dependency> <groupId>com.alibaba</groupId> <artifactId>fastjson</artifactId> <!-- 如果上面没定义版本，这里必须写 --> <version>1.2.83</version> <!-- scope: 控制依赖生效范围 --> <scope>compile</scope> <!-- 默认：编译+运行+测试都有效 --> <!-- <scope>provided</scope> --> <!-- 由容器提供(如 Tomcat)，打包时不包含 --> <!-- <scope>runtime</scope> --> <!-- 仅运行和测试有效，编译不可见 --> <!-- <scope>test</scope> --> <!-- 仅测试有效 (如 JUnit) --> <!-- optional: 是否传递依赖 --> <optional>true</optional> <!-- true: 下游模块不会自动继承此依赖 --> <!-- exclusions: 排除传递依赖 (解决冲突神器) --> <exclusions> <exclusion> <groupId>commons-logging</groupId> <artifactId>commons-logging</artifactId> </exclusion> </exclusions> </dependency>
🏗️ 三、构建配置 (Build Configuration)
作用：定制编译、打包、资源处理等行为。
1. <build> 根标签
<build>
<!-- 最终生成的包名 (默认是 artifactId-version) -->
<finalName>my-shop-order-service</finalName>
<!-- 资源文件配置 (src/main/resources) -->
<resources>
<resource>
<directory>src/main/resources</directory>
<filtering>true</filtering> <!-- 开启变量替换 (${app.name}) -->
<includes>
<include>**/*.properties</include>
<include>**/*.yml</include>
</includes>
</resource>
</resources>
<!-- 插件配置 -->
<plugins>
<!-- 编译插件 -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.11.0</version>
<configuration>
<source>17</source> <!-- JDK 源码版本 -->
<target>17</target> <!-- 字节码版本 -->
<encoding>UTF-8</encoding>
</configuration>
</plugin>
<!-- 打包插件 (Jar/War) -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-jar-plugin</artifactId>
<configuration>
<archive>
<manifest>
<mainClass>com.example.Application</mainClass> <!-- 指定启动类 -->
</manifest>
</archive>
</configuration>
</plugin>
<!-- Spring Boot 打包插件 (可执行 Jar) -->
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<executions>
<execution>
<goals>
<goal>repackage</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
<!-- 插件统一管理 (类似 dependencyManagement) -->
<pluginManagement>
<plugins>
<!-- 在这里定义插件版本，子模块引用时可不写 version -->
</plugins>
</pluginManagement>
</build>👨👩👧👦 四、多模块与继承 (Inheritance & Aggregation)
作用：管理大型分布式项目。
1. <parent> (继承)
-
位置 ：子模块
pom.xml。 -
作用：继承父工程的依赖管理、插件配置、属性等。
com.example my-shop-parent 1.0.0-SNAPSHOT ../parent/pom.xml
2. <modules> (聚合)
-
位置 ：父工程
pom.xml。 -
作用：声明包含哪些子模块，构建父工程时会一并构建所有子模块。
-
注意 ：父工程的
<packaging>必须是pom。com.example my-shop-parent 1.0.0-SNAPSHOT pom <modules> <module>my-shop-common</module> <module>my-shop-order</module> <module>my-shop-user</module> <module>my-shop-gateway</module> </modules>
⚙️ 五、高级配置 (Profiles, Properties, Repositories)
1. <properties> (全局变量)
-
作用：定义版本变量，方便统一修改。
17 ${java.version} UTF-8 <!-- 自定义依赖版本 --> <lombok.version>1.18.30</lombok.version> <mysql.version>8.0.33</mysql.version>
用法 ：在依赖中写 <version>${mysql.version}</version>。
2. <profiles> (环境切换)
-
作用：针对不同环境 (dev, test, prod) 激活不同配置。
dev development jdbc:mysql://localhost:3306/dev_db true <!-- 生产环境 --> <profile> <id>prod</id> <properties> <env>production</env> <db.url>jdbc:mysql://prod-cluster:3306/prod_db</db.url> </properties> <!-- 激活方式: mvn clean package -P prod --> </profile>
3. <repositories> & <pluginRepositories> (仓库)
-
作用：当中央仓库没有包时，配置私有仓库 (如 Nexus, Artifactory) 或镜像。
aliyun-public Aliyun Public Repository https://maven.aliyun.com/repository/public true false
🚀 速查总结表
表格
| 标签层级 | 核心标签 | 一句话作用 | 会不会下载 Jar？ |
|---|---|---|---|
| 根节点 | groupId/artifactId/version |
项目身份证 | 否 |
| 依赖 | dependencyManagement |
定版本 (字典) | ❌ 否 |
| 依赖 | dependencies |
用依赖 (下载) | ✅ 是 |
| 依赖项 | scope |
控制生效范围 (compile/test/provided) | - |
| 依赖项 | exclusions |
排除冲突的子依赖 | - |
| 构建 | build/plugins |
配置编译/打包插件 | - |
| 多模块 | parent |
继承父配置 | - |
| 多模块 | modules |
聚合子模块 | - |
| 变量 | properties |
定义 ${version} 变量 |
- |
| 环境 | profiles |
切换 dev/test/prod | - |
💡 常见避坑指南
- 版本冲突 ：优先在父工程的
<dependencyManagement>中统一版本，子模块不要随意写<version>。 - 包打不进去 ：检查是否把依赖错写在了
<dependencyManagement>里（记得移到<dependencies>）。 - 找不到类 ：检查
<scope>是否误设为provided或test。 - 父子版本不一致 ：子模块的
<parent>版本必须与父工程<version>严格一致（除非使用特殊策略）。 - BOM 引入无效 ：引入 BOM 时必须加
<type>pom</type>和<scope>import</scope>。