您现在的位置：程式碼之家 >> 編程語言 > >> Java 程式設計 >> Java 綜合教學

Maven POM.xml 核心配置全解析：從坐標、依賴、構建到 Profile 與分發管理

編輯：Java 綜合教學

Maven POM.xml 完整配置指南：超詳細元素解析與最佳實踐模板

POM (Project Object Model) 是 Maven 專案的核心描述文件。本文系統拆解 pom.xml 所有核心區塊——坐標、繼承、依賴管理、構建生命周期、插件、Profile、倉庫、分發——並提供生產級模板與避坑指南。

一、POM 根元素與坐標 (GAV)

<project xmlns="https://maven.apache.org/POM/4.0.0"
         xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="https://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    
    <!-- 坐標 GAV：全局唯一標識 -->
    <groupId>com.mycompany</groupId>       <!-- 組織/公司域名反轉 -->
    <artifactId>my-app</artifactId>           <!-- 專案名稱，小寫連字符 -->
    <version>1.0.0-SNAPSHOT</version>        <!-- 語義化版本：主.次.修-狀態 -->
    <packaging>jar</packaging>                <!-- jar/war/pom/ear 等 -->
    
    <name>My Application</name>
    <description>項目詳細描述</description>
    <url>https://github.com/mycompany/my-app</url>
</project>

二、繼承與聚合 (多模組)

父項目 (packaging=pom)

<parent>
    <groupId>com.mycompany</groupId>
    <artifactId>parent-pom</artifactId>
    <version>1.0.0</version>
    <relativePath>../parent/pom.xml</relativePath> <!-- 相對路徑，空值禁用查找 -->
</parent>

聚合模組 (父項目中聲明)

<modules>
    <module>common</module>
    <module>service</module>
    <module>web</module>
</modules>

三、屬性管理 (`<properties>`)

<properties>
    <!-- 內建屬性引用：${project.version}, ${maven.compiler.source} -->
    <java.version>17</java.version>
    <maven.compiler.source>${java.version}</maven.compiler.source>
    <maven.compiler.target>${java.version}</maven.compiler.target>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
    
    <!-- 統一依賴版本 (BOM 風格) -->
    <spring-boot.version>3.2.0</spring-boot.version>
    <junit.version>5.10.2</junit.version>
</properties>

四、依賴管理核心 (`<dependencies>` & `<dependencyManagement>`)

依賴範圍 (`scope`) 速查

scope	編譯類路徑	測試類路徑	運行類路徑	典型場景
compile (默認)	✅	✅	✅	業務代碼依賴
provided	✅	✅	❌	Servlet API、容器提供
runtime	❌	✅	✅	JDBC 驅動、日誌實現
test	❌	✅	❌	JUnit、Mockito
system	✅	✅	❌	本地 JAR (systemPath)，不推薦
import	—	—	—	僅用於 dependencyManagement 引入 BOM

依賴傳遞與排除

<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-context</artifactId>
    <version>${spring.version}</version>
    <exclusions>
        <exclusion>
            <groupId>commons-logging</groupId>
            <artifactId>commons-logging</artifactId>
        </exclusion>
    </exclusions>
</dependency>

dependencyManagement 統一版本 (父項目/ BOM)

<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>
<!-- 子項目無需寫版本 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

五、構建配置 (`<build>`)

資源過濾與目錄

<build>
    <sourceDirectory>src/main/java</sourceDirectory>
    <testSourceDirectory>src/test/java</testSourceDirectory>
    <resources>
        <resource>
            <directory>src/main/resources</directory>
            <filtering>true</filtering> <!-- 啟用 ${property} 替換 -->
            <includes><include>**/*.yml</include><include>**/*.properties</include></includes>
        </resource>
    </resources>
    <testResources>
        <testResource>
            <directory>src/test/resources</directory>
            <filtering>true</filtering>
        </testResource>
    </testResources>
    
    <outputDirectory>target/classes</outputDirectory>
    <testOutputDirectory>target/test-classes</testOutputDirectory>
</build>

核心插件配置模板

<build>
    <plugins>
        <!-- 編譯器 -->
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.12.1</version>
            <configuration>
                <source>${maven.compiler.source}</source>
                <target>${maven.compiler.target}</target>
                <encoding>${project.build.sourceEncoding}</encoding>
                <parameters>true</parameters> <!-- 保留參數名，Spring 必需 -->
            </configuration>
        </plugin>
        
        <!-- 單元測試 -->
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-surefire-plugin</artifactId>
            <version>3.2.2</version>
            <configuration>
                <includes><include>**/*Test.java</include></includes>
                <argLine>-Dfile.encoding=UTF-8</argLine>
            </configuration>
        </plugin>
        
        <!-- 打包 (Jar/War) -->
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-jar-plugin</artifactId>
            <version>3.4.2</version>
            <configuration>
                <archive>
                    <manifest>
                        <addClasspath>true</addClasspath>
                        <classpathPrefix>lib/</classpathPrefix>
                        <mainClass>com.mycompany.Main</mainClass>
                    </manifest>
                </archive>
            </configuration>
        </plugin>
        
        <!-- 源碼/文檔打包 -->
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-source-plugin</artifactId>
            <version>3.3.1</version>
            <executions><execution><id>attach-sources</id><goals><goal>jar</goal></goals></execution></executions>
        </plugin>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-javadoc-plugin</artifactId>
            <version>3.6.0</version>
            <executions><execution><id>attach-javadocs</id><goals><goal>jar</goal></goals></execution></executions>
        </plugin>
    </plugins>
</build>

六、Profile 多環境配置

<profiles>
    <profile>
        <id>dev</id>
        <activation>
            <activeByDefault>true</activeByDefault> <!-- 默認激活 -->
            <!-- 或 property 激活：-Denv=dev -->
            <property><name>env</name><value>dev</value></property>
        </activation>
        <properties>
            <db.url>jdbc:mysql://localhost:3306/dev</db.url>
            <log.level>DEBUG</log.level>
        </properties>
    </profile>
    <profile>
        <id>prod</id>
        <activation><property><name>env</name><value>prod</value></property></activation>
        <properties>
            <db.url>jdbc:mysql://prod-host:3306/prod</db.url>
            <log.level>WARN</log.level>
        </properties>
    </profile>
</profiles>

啟動：mvn clean package -Pprod 或 mvn clean package -Denv=prod。

七、倉庫與分發管理

私服配置 (distributionManagement)

<distributionManagement>
    <repository>
        <id>releases</id>
        <name>Internal Releases</name>
        <url>https://nexus.mycompany.com/repository/maven-releases/</url>
    </repository>
    <snapshotRepository>
        <id>snapshots</id>
        <name>Internal Snapshots</name>
        <url>https://nexus.mycompany.com/repository/maven-snapshots/</url>
    </snapshotRepository>
</distributionManagement>

settings.xml 鏈接 (認證)

<servers>
    <server>
        <id>releases</id>
        <username>deployer</username>
        <password>xxx</password>
    </server>
    <server>
        <id>snapshots</id>
        <username>deployer</username>
        <password>xxx</password>
    </server>
</servers>

八、生產級最佳實踐清單

版本鎖定：所有插件、依賴**必須鎖定版本**，避免構建不可重現。
BOM 統一：引入 spring-boot-dependencies 等 BOM，子項目省略版本號。
編碼統一：UTF-8 覆蓋 source/reporting/compiler/資源過濾。
參數名保留：maven-compiler-plugin <parameters>true</parameters>，Spring/反射依賴。
跳過測試構建：-DskipTests (編譯測試但不執行) vs -Dmaven.test.skip=true (完全跳過)。
強制更新快照：-U 強制檢查遠程 SNAPSHOT 更新。
離線模式：-o 僅使用本地倉庫，CI 緩存優化。
Wrapper 使用：mvnw 綁定 Maven 版本，避免環境差異。

九、最小化生產模板 (複製即用)

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="https://maven.apache.org/POM/4.0.0" xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="https://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.example</groupId>
    <artifactId>demo</artifactId>
    <version>1.0.0</version>
    <packaging>jar</packaging>
    
    <properties>
        <java.version>17</java.version>
        <maven.compiler.source>${java.version}</maven.compiler.source>
        <maven.compiler.target>${java.version}</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>
    
    <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>
    
    <dependencies>
        <dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency>
        <dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-test</artifactId><scope>test</scope></dependency>
    </dependencies>
    
    <build>
        <plugins>
            <plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-compiler-plugin</artifactId><version>3.12.1</version>
                <configuration><parameters>true</parameters></configuration></plugin>
            <plugin><groupId>org.springframework.boot</groupId><artifactId>spring-boot-maven-plugin</artifactId><version>3.2.0</version></plugin>
        </plugins>
    </build>
</project>