Maven 标签大全

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 包。子模块引用时可省略版本号。

• 场景：父工程统一管控所有子模块的依赖版本。

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

        <!-- 手动锁定某个特定依赖的版本 -->
        <dependency>
            <groupId>com.google.guava</groupId>
            <artifactId>guava</artifactId>
            <version>32.1.3-jre</version>
        </dependency>
    </dependencies>

  </dependencyManagement>

2. <dependencies> (实际依赖)

• 特点 ：真正下载 Jar 包，加入 Classpath。

• 场景：当前模块实际需要用到的库。

  <dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency>

    <!-- 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>

  </dependencies>

---

🏗️ 三、构建配置 (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。

• 作用：继承父工程的依赖管理、插件配置、属性等。

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

2. <modules> (聚合)

• 位置 ：父工程 pom.xml。

• 作用：声明包含哪些子模块，构建父工程时会一并构建所有子模块。

• 注意 ：父工程的 <packaging> 必须是 pom。

  <project> <groupId>com.example</groupId> <artifactId>my-shop-parent</artifactId> <version>1.0.0-SNAPSHOT</version> <packaging>pom</packaging>

    <modules>
        <module>my-shop-common</module>
        <module>my-shop-order</module>
        <module>my-shop-user</module>
        <module>my-shop-gateway</module>
    </modules>

  </project>

---

⚙️ 五、高级配置 (Profiles, Properties, Repositories)

1. <properties> (全局变量)

• 作用：定义版本变量，方便统一修改。

  <properties> <java.version>17</java.version> <maven.compiler.source>${java.version}</maven.compiler.source> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>

    <!-- 自定义依赖版本 -->
    <lombok.version>1.18.30</lombok.version>
    <mysql.version>8.0.33</mysql.version>

  </properties>

用法 ：在依赖中写 <version>${mysql.version}</version>。

2. <profiles> (环境切换)

• 作用：针对不同环境 (dev, test, prod) 激活不同配置。

  <profiles> <profile> <id>dev</id> <properties> <env>development</env> <db.url>jdbc:mysql://localhost:3306/dev_db</db.url> </properties> <activation> <activeByDefault>true</activeByDefault> </activation> </profile>

    <!-- 生产环境 -->
    <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>

  </profiles>

3. <repositories> & <pluginRepositories> (仓库)

• 作用：当中央仓库没有包时，配置私有仓库 (如 Nexus, Artifactory) 或镜像。

  <repositories> <repository> <id>aliyun-public</id> <name>Aliyun Public Repository</name> <url>https://maven.aliyun.com/repository/public</url> <releases> <enabled>true</enabled> </releases> <snapshots> <enabled>false</enabled> </snapshots> </repository> </repositories>

---

🚀 速查总结表

表格

标签层级	核心标签	一句话作用	会不会下载 Jar？
根节点	groupId/artifactId/version	项目身份证	否
依赖	dependencyManagement	定版本 (字典)	❌ 否
依赖	dependencies	用依赖 (下载)	✅ 是
依赖项	scope	控制生效范围 (compile/test/provided)	-
依赖项	exclusions	排除冲突的子依赖	-
构建	build/plugins	配置编译/打包插件	-
多模块	parent	继承父配置	-
多模块	modules	聚合子模块	-
变量	properties	定义 ${version} 变量	-
环境	profiles	切换 dev/test/prod	-

💡 常见避坑指南

1. 版本冲突 ：优先在父工程的 <dependencyManagement> 中统一版本，子模块不要随意写 <version>。
2. 包打不进去 ：检查是否把依赖错写在了 <dependencyManagement> 里（记得移到 <dependencies>）。
3. 找不到类 ：检查 <scope> 是否误设为 provided 或 test。
4. 父子版本不一致 ：子模块的 <parent> 版本必须与父工程 <version> 严格一致（除非使用特殊策略）。
5. BOM 引入无效 ：引入 BOM 时必须加 <type>pom</type> 和 <scope>import</scope>。