Maven 核心配置詳解：pom.xml 全面指南

什麼是 POM？

POM（Project Object Model，專案物件模型）是 Maven 專案的核心配置檔，以 pom.xml 形式存在。它完整描述專案的座標、依賴關係、建置設定、報表、版本庫、部署資訊等所有專案相關因素。

POM 基本架構速覽

<project>
  <modelVersion>4.0.0</modelVersion>
  <!-- 基本座標 -->
  <groupId>...</groupId>
  <artifactId>...</artifactId>
  <version>...</version>
  <packaging>...</packaging>
  <dependencies>...</dependencies>
  <parent>...</parent>
  <dependencyManagement>...</dependencyManagement>
  <modules>...</modules>
  <properties>...</properties>
  <!-- 建置設定 -->
  <build>...</build>
  <reporting>...</reporting>
  <!-- 專案資訊 -->
  <name>...</name>
  <description>...</description>
  <url>...</url>
  <inceptionYear>...</inceptionYear>
  <licenses>...</licenses>
  <organization>...</organization>
  <developers>...</developers>
  <contributors>...</contributors>
  <!-- 環境設定 -->
  <issueManagement>...</issueManagement>
  <ciManagement>...</ciManagement>
  <mailingLists>...</mailingLists>
  <scm>...</scm>
  <prerequisites>...</prerequisites>
  <repositories>...</repositories>
  <pluginRepositories>...</pluginRepositories>
  <distributionManagement>...</distributionManagement>
  <profiles>...</profiles>
</project>

核心座標元素

• groupId：專案或組織的唯一識別碼，對應倉庫路徑（如 org.codehaus.mojo → /org/codehaus/mojo）。
• artifactId：專案通用名稱。
• version：專案版本號。
• packaging：打包類型（jar、war、ear、pom 等）。
• classifier：附加分類標識。

依賴關係管理

基本依賴宣告

<dependencies>
  <dependency>
    <groupId>junit</groupId>
    <artifactId>junit</artifactId>
    <version>4.0</version>
    <type>jar</type>
    <scope>test</scope>
    <optional>true</optional>
  </dependency>
</dependencies>

scope（依賴範圍）：

• compile（預設）：編譯、測試、執行皆需。
• provided：編譯、測試需，執行時由容器/JDK 提供（如 Servlet API）。
• runtime：僅執行與測試需（如 JDBC 驅動）。
• test：僅測試階段需（如 JUnit）。
• system：類似 provided，但需指定 systemPath（不建議使用）。

排除傳遞性依賴

<dependency>
  <groupId>org.apache.maven</groupId>
  <artifactId>maven-embedder</artifactId>
  <version>2.0</version>
  <exclusions>
    <exclusion>
      <groupId>org.apache.maven</groupId>
      <artifactId>maven-core</artifactId>
    </exclusion>
  </exclusions>
</dependency>

解決版本衝突的關鍵手段。

繼承與多模組

父專案定義

<project>
  <modelVersion>4.0.0</modelVersion>
  <groupId>org.codehaus.mojo</groupId>
  <artifactId>my-parent</artifactId>
  <version>2.0</version>
  <packaging>pom</packaging>
</project>

子專案繼承

<project>
  <parent>
    <groupId>org.codehaus.mojo</groupId>
    <artifactId>my-parent</artifactId>
    <version>2.0</version>
    <relativePath>../my-parent</relativePath>
  </parent>
  <artifactId>my-project</artifactId>
</project>

dependencyManagement 可在父專案統一管控依賴版本與範圍，子專案引用時可省略版本號。

多模組聚合

<modules>
  <module>my-project1</module>
  <module>my-project2</module>
</modules>

建置設定深度解析

基礎建置元素

<build>
  <defaultGoal>install</defaultGoal>
  <directory>${basedir}/target</directory>
  <finalName>${artifactId}-${version}</finalName>
  <filters>
    <filter>filters/filter1.properties</filter>
  </filters>
</build>

資源檔管理

<resources>
  <resource>
    <targetPath>META-INF/plexus</targetPath>
    <filtering>false</filtering>
    <directory>${basedir}/src/main/plexus</directory>
    <includes><include>configuration.xml</include></includes>
    <excludes><exclude>**/*.properties</exclude></excludes>
  </resource>
</resources>

外掛程式配置

<plugins>
  <plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-jar-plugin</artifactId>
    <version>2.0</version>
    <configuration>
      <classifier>test</classifier>
    </configuration>
    <executions>
      <execution>
        <id>echodir</id>
        <goals><goal>run</goal></goals>
        <phase>verify</phase>
        <configuration>
          <tasks><echo>Build Dir: ${project.build.directory}</echo></tasks>
        </configuration>
      </execution>
    </executions>
  </plugin>
</plugins>

關鍵屬性：extensions（是否載入擴充）、inherited（是否繼承給子專案）、executions（綁定生命週期階段與目標）。

目錄結構自訂

<sourceDirectory>${basedir}/src/main/java</sourceDirectory>
<testSourceDirectory>${basedir}/src/test/java</testSourceDirectory>
<outputDirectory>${basedir}/target/classes</outputDirectory>

擴充套件

<extensions>
  <extension>
    <groupId>org.apache.maven.wagon</groupId>
    <artifactId>wagon-ftp</artifactId>
    <version>1.0-alpha-3</version>
  </extension>
</extensions>

報表設定

<reporting>
  <plugins>
    <plugin>
      <artifactId>maven-project-info-reports-plugin</artifactId>
      <reportSets>
        <reportSet>
          <id>sunlink</id>
          <reports><report>javadoc</report></reports>
          <configuration>
            <links><link>https://java.sun.com/j2se/1.5.0/docs/api/</link></links>
          </configuration>
        </reportSet>
      </reportSets>
    </plugin>
  </plugins>
</reporting>

專案資訊與環境設定

• Licenses：授權條款與連結。
• Organization：組織名稱與網址。
• Developers/Contributors：開發者與貢獻者詳細資訊。
• Issue Management：缺陷追蹤系統（Bugzilla、JIRA 等）。
• CI Management：持續整合伺服器設定。
• SCM：版本控制資訊（Git/SVN 連結）。
• Repositories/Plugin Repositories：遠端倉庫設定。

部署管理

distributionManagement 定義成品發布位置，支援檔案系統、SCP、SFTP、FTP 等協定，需搭配 settings.xml 的 server 認證。

<distributionManagement>
  <repository>
    <id>proficio-repository</id>
    <url>scp://sshserver.yourcompany.com/deploy</url>
  </repository>
</distributionManagement>

Profiles 進階應用

POM 中的 profiles 可根據環境（JDK 版本、OS、屬性、檔案存在與否）自動啟動，支援覆蓋大部分建置設定。