Maven ＜pom.xml＞ 标签详尽教程

先看一个最小 POM 模板（上下文）

<project xmlns="http://maven.apache.org/POM/4.0.0"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation="http://maven.apache.org/POM/4.0.0http://maven.apache.org/xsd/maven-4.0.0.xsd"><modelVersion>4.0.0</modelVersion><!-- 其余标签见下方分类 -->
</project>

---

一、项目信息与标识（Project info）

• <modelVersion>
  用途：指定 POM 模型版本（目前恒为 4.0.0）。
  示例：

  <modelVersion>4.0.0</modelVersion>
  

• <groupId>
  用途：组织或公司标识，类似 Java 包名前缀，组成坐标的一部分。
  示例：

  <groupId>com.example</groupId>
  

• <artifactId>
  用途：模块/项目的名称（在同一 groupId 下唯一）。
  示例：

  <artifactId>my-app</artifactId>
  

• <version>
  用途：项目版本（语义化版本或其它约定）。
  示例：

  <version>1.0.0</version>
  

• <packaging>
  用途：指定打包类型（如 jar、war、pom、ear）。jar 为默认。
  示例：

  <packaging>jar</packaging>
  

• <name>、<description>、<url>
  用途：人类可读的项目名称、描述与项目主页（通常用于生成站点或 POM 元数据）。
  示例：

  <name>My App</name>
  <description>A demo Maven project</description>
  <url>https://example.com/my-app</url>
  

• <parent>
  用途：继承自父 POM（用于共享版本/插件/配置）。子模块通过 parent 继承依赖管理、插件配置等。
  示例：

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

• <modules>
  用途：多模块（multi-module）父 POM 使用，用于列出子模块目录。
  示例：

  <modules><module>service-a</module><module>service-b</module>
  </modules>
  

• <scm>
  用途：源代码管理信息（用于 mvn release、site 等）。
  示例：

  <scm><connection>scm:git:git://github.com/you/repo.git</connection><developerConnection>scm:git:ssh://github.com:you/repo.git</developerConnection><url>https://github.com/you/repo</url>
  </scm>
  

---

二、属性与版本管理（Properties & Versioning）

• <properties>
  用途：集中声明可复用的变量（版本号、编译参数、编码等），在 POM 中用 ${...} 引用。
  示例：

  <properties><java.version>17</java.version><project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  </properties>
  

• <dependencyManagement>
  用途：在父 POM 中声明依赖的版本与范围等“默认值”，子模块只需声明 groupId/artifactId 即可继承版本，便于统一管理版本。注意：声明在 dependencyManagement 的依赖不会自动加入 classpath，仍需在 <dependencies> 中引用。
  示例：

  <dependencyManagement><dependencies><dependency><groupId>com.fasterxml.jackson.core</groupId><artifactId>jackson-databind</artifactId><version>2.15.0</version></dependency></dependencies>
  </dependencyManagement>
  

---

三、依赖相关标签（Dependencies）

• <dependencies> / <dependency>
  用途：声明项目运行/编译/测试所需的库。每个 <dependency> 包含 groupId, artifactId, version（除非由 dependencyManagement 管理）。
  示例：

  <dependencies><dependency><groupId>org.springframework</groupId><artifactId>spring-context</artifactId><version>5.3.27</version></dependency>
  </dependencies>
  

• <scope>
  用途：指定依赖作用域：compile（默认）、provided、runtime、test、system、import（用于 BOM）。影响传递性与打包。
  示例（测试依赖）：

  <dependency><groupId>junit</groupId><artifactId>junit</artifactId><version>4.13.2</version><scope>test</scope>
  </dependency>
  

• <optional>
  用途：标记依赖为“可选”，表示使用你的包的项目不会自动继承此依赖。
  示例：

  <optional>true</optional>
  

• <exclusions> / <exclusion>
  用途：排除某个传递依赖（避免冲突或不需要的传递包）。
  示例（排除 Tomcat）：

  <dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId><exclusions><exclusion><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-tomcat</artifactId></exclusion></exclusions>
  </dependency>
  

• <type> / <classifier> / <systemPath>（不常用）
  用途：<type> 指明构件类型（例如 jar/war/zip），<classifier> 用于有变体的工件（例如 tests、sources），system scope 需配合 systemPath（通常应避免使用）。
  示例（classifier）：

  <dependency><groupId>org.example</groupId><artifactId>lib</artifactId><version>1.0</version><classifier>tests</classifier>
  </dependency>
  

---

四、构建与插件（Build & Plugins）

• <build>
  用途：构建相关设置的根节点（finalName、plugins、resources 等）。
  示例：

  <build><finalName>my-app</finalName>
  </build>
  

• <finalName>
  用途：构建输出的最终文件名（不含扩展名），例如 target/my-app.jar。
  示例：

  <finalName>my-app-release</finalName>
  

• <resources> / <resource> / <testResources>
  用途：指定资源文件目录与过滤（resource filtering）。
  示例（启用资源过滤）：

  <resources><resource><directory>src/main/resources</directory><filtering>true</filtering></resource>
  </resources>
  

• <plugins> / <plugin>
  用途：配置 Maven 插件（编译、打包、测试、发布等）。推荐始终指定插件版本以保证可重复构建。
  示例（maven-compiler-plugin）：

  <build><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>
  </build>
  

• <executions> / <execution> / <goals> / <goal>
  用途：设置插件在特定构建阶段执行的目标（可配置多个 execution）。
  示例（shade 打包成 fat-jar）：

  <plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-shade-plugin</artifactId><version>3.5.0</version><executions><execution><phase>package</phase><goals><goal>shade</goal></goals><configuration><transformers><transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer"><mainClass>com.example.Main</mainClass></transformer></transformers></configuration></execution></executions>
  </plugin>
  

• <pluginManagement>
  用途：在父 POM 中集中声明插件版本/配置的默认值，子模块可以继承或覆盖。与 dependencyManagement 类似，但针对插件。
  示例：

  <pluginManagement><plugins><plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-compiler-plugin</artifactId><version>3.11.0</version></plugin></plugins>
  </pluginManagement>
  

---

五、Profiles（构建配置切换）

• <profiles> / <profile>
  用途：定义不同环境/场景的构建变体（如 dev、prod、CI）。profile 可以修改依赖、插件配置、properties 等；可通过命令行 -P 激活或通过激活条件自动启用。
  示例（按属性激活的 profile）：

  <profiles><profile><id>prod</id><activation><property><name>env</name><value>prod</value></property></activation><properties><app.env>production</app.env></properties></profile>
  </profiles>
  

  激活方式：mvn clean package -Denv=prod

---

六、仓库与发布（Repositories & Distribution）

• <repositories> / <repository>
  用途：声明构件下载仓库（除了默认 Maven Central，可声明私服或公司内网仓库）。
  示例：

  <repositories><repository><id>company-repo</id><url>https://repo.example.com/maven2</url></repository>
  </repositories>
  

• <pluginRepositories>
  用途：为插件下载指定仓库（插件也需要仓库来源）。
  示例：

  <pluginRepositories><pluginRepository><id>company-plugins</id><url>https://repo.example.com/plugins</url></pluginRepository>
  </pluginRepositories>
  

• <distributionManagement>
  用途：配置发布（deploy）目标仓库（release 和 snapshot 分开）。发布凭据和服务器 id 通常在 ~/.m2/settings.xml 中配置。
  示例：

  <distributionManagement><repository><id>releases</id><url>https://repo.example.com/releases</url></repository><snapshotRepository><id>snapshots</id><url>https://repo.example.com/snapshots</url></snapshotRepository>
  </distributionManagement>
  

  注意：不要在 POM 中把凭据写明，安全凭据放 settings.xml。

---

七、元数据（开发者、许可证、CI、问题跟踪）

• <developers> / <developer>
  用途：记录项目开发者信息（名字、邮箱、id），用于项目文档与站点。
  示例：

  <developers><developer><id>alice</id><name>Alice Zhang</name><email>[e-mail]</email></developer>
  </developers>
  

• <licenses> / <license>
  用途：声明项目使用的开源许可证（便于遵从性检查）。
  示例：

  <licenses><license><name>Apache License, Version 2.0</name><url>http://www.apache.org/licenses/LICENSE-2.0.txt</url></license>
  </licenses>
  

• <ciManagement>、<issueManagement>、<mailingLists>
  用途：CI 服务、问题跟踪、邮件列表的元信息（主要用于 site/发布）。示例略。

---

八、典型 POM 实战示例（组合）

1. 最小可用 POM

<project ...><modelVersion>4.0.0</modelVersion><groupId>com.example</groupId><artifactId>demo</artifactId><version>0.1.0</version>
</project>

1. 使用 properties + dependencyManagement 的父 POM（片段）

<project ...><modelVersion>4.0.0</modelVersion><groupId>com.example</groupId><artifactId>parent</artifactId><version>1.0.0</version><packaging>pom</packaging><properties><java.version>17</java.version><jackson.version>2.15.0</jackson.version></properties><dependencyManagement><dependencies><dependency><groupId>com.fasterxml.jackson.core</groupId><artifactId>jackson-databind</artifactId><version>${jackson.version}</version></dependency></dependencies></dependencyManagement><pluginManagement><plugins><plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-compiler-plugin</artifactId><version>3.11.0</version></plugin></plugins></pluginManagement>
</project>

子模块可以只写 <dependency> 而不写 <version>。

1. 打包可执行 fat-jar（关键插件片段）

<build><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><!-- 打包成可执行 jar --><plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-shade-plugin</artifactId><version>3.5.0</version><executions><execution><phase>package</phase><goals><goal>shade</goal></goals><configuration><createDependencyReducedPom>true</createDependencyReducedPom><transformers><transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer"><mainClass>com.example.Main</mainClass></transformer></transformers></configuration></execution></executions></plugin></plugins>
</build>

---

九、最佳实践与常见陷阱

• 统一版本管理：尽量在父 POM 使用 <dependencyManagement> 或 <properties> 管理版本，避免子模块间依赖冲突。

• 总是指定插件版本：不显式指定插件版本会导致不同环境构建结果不一致。

• 避免 system scope：system 依赖不可移植，应使用私服或安装到本地仓库。

• 不要把凭据写进 POM：发布仓库的用户名/密码放在 ~/.m2/settings.xml（server 节点）中。

• 使用 mvn help:effective-pom：查看合并后实际生效的 POM（包含继承与 profile）。

• 谨慎使用资源过滤：默认会替换 ${...}，若过滤错误可能破坏二进制文件（对资源目录做过滤时要小心仅过滤文本文件）。