Maven 屬性完整指南：六大類別、使用場景與最佳實踐

Maven 屬性完整指南：六大類別、使用場景與最佳實踐

Maven 屬性系統是構建靈活性的核心，支援在 POM、Settings、命令列、環境變數等多個層面定義與引用變數。掌握屬性分類、優先級與解析機制，能讓構建配置更乾淨、可移植、易維護。

一、Maven 屬性六大來源分類

1. 內建屬性

Maven 核心預定義，無需聲明即可直接使用：

2. POM 專案屬性

對應 pom.xml 中元素的值，採用 project. 前綴：

3. 自定義屬性

在 <properties> 區塊自定義，專案級全域常量：

<properties>
    <java.version>17</java.version>
    <spring-boot.version>3.2.0</spring-boot.version>
    <docker.image.prefix>mycompany</docker.image.prefix>
    <skipTests>false</skipTests>
</properties>

引用方式：${java.version}、${spring-boot.version}

4. Settings 屬性

對應 settings.xml 元素，採用 settings. 前綴：

• ${settings.localRepository}：本地倉庫路徑 (預設 ~/.m2/repository)
• ${settings.offline}：離線模式開關
• ${settings.proxies}、${settings.servers}、${settings.mirrors}：代理/伺服器/鏡像配置

5. Java 系統屬性

所有 System.getProperties() 可用屬性，無前綴直接引用：

6. 環境變數屬性

所有作業系統環境變數，採用 env. 前綴：

• ${env.JAVA_HOME} → JAVA_HOME 環境變數值
• ${env.PATH} → PATH 環境變數值
• ${env.CI} → CI 環境標識 (GitHub Actions/GitLab CI 常設為 true)
• ${env.BUILD_NUMBER} → Jenkins 建構編號

二、屬性解析優先級 (高 → 低)

1. 命令列參數：mvn -DskipTests=true clean install
2. POM <properties> 定義
3. 父 POM <properties> 繼承
4. Settings.xml <properties>
5. Java 系統屬性 / 環境變數
6. Maven 內建預設值

實戰技巧：命令列 -D 參數可覆蓋所有層級屬性，是 CI/CD 動態注入版本號、環境標識的標準方式。

三、屬性引用語法與進階用法

1. 基礎引用

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <configuration>
        <source>${java.version}</source>
        <target>${java.version}</target>
    </configuration>
</plugin>

2. 屬性嵌套引用

<properties>
    <java.version>17</java.version>
    <maven.compiler.source>${java.version}</maven.compiler.source>
    <maven.compiler.target>${java.version}</maven.compiler.target>
    <project.build.outputEncoding>UTF-8</project.build.outputEncoding>
    <docker.image.name>${docker.image.prefix}/${project.artifactId}</docker.image.name>
</properties>

3. 條件屬性 (Profile 中)

<profiles>
    <profile>
        <id>prod</id>
        <properties>
            <env.name>production</env.name>
            <db.url>jdbc:mysql://prod-db:3306/app</db.url>
        </properties>
    </profile>
    <profile>
        <id>dev</id>
        <activation>
            <activeByDefault>true</activeByDefault>
        </activation>
        <properties>
            <env.name>development</env.name>
            <db.url>jdbc:mysql://localhost:3306/app</db.url>
        </properties>
    </profile>
</profiles>

4. 檔案過濾資源置換

<build>
    <resources>
        <resource>
            <directory>src/main/resources</directory>
            <filtering>true</filtering>  <!-- 啟用屬性置換 -->
            <includes><include>**/*.yml</include><include>**/*.properties</include></includes>
        </resource>
    </resources>
</build>

資源檔案中即可使用：app.version=${project.version}、build.time=${maven.build.timestamp}

四、常用內建時間屬性

需啟用 maven-build-timestamp 外掛或使用 maven-antrun-plugin：

• ${maven.build.timestamp}：預設格式 yyyyMMdd-HHmm
• 自訂格式：<maven.build.timestamp.format>yyyy-MM-dd HH:mm:ss</maven.build.timestamp.format>

五、最佳實踐總結

1. 版本統一管理：所有依賴版本集中在 <properties>，配合 dependencyManagement
2. 環境隔離：資料庫連線、服務地址等敏感配置用 Profile + 環境變數區分
3. 避免硬編碼路徑：統一使用 ${project.basedir}、${project.build.directory}
4. 命名規範：自定義屬性採用小寫點分隔 (如 spring.boot.version)，避免與系統屬性衝突
5. 敏感資訊外部化：密碼、Token 等絕不寫入 POM，用 settings.xml <servers> 或環境變數注入
6. 善用 help:effective-pom：mvn help:effective-pom 查看最終解析後的屬性值

六、常見問題排查

Maven 屬性系統看似簡單，實則是構建自動化的骨架。合理設計屬性體系，能讓專案從開發、測試到生產環境的構建過程實現真正的「一次編寫，到處構建」。