Maven Profiles 完整指南：定義、啟動與最佳實務

什麼是 Profile？

Profile 定義建置生命週期中使用的環境變體，可根據作業系統、JDK 版本、資料庫類型等條件自動啟動，實現「一次配置，多環境構建」。

Profile 定義位置與優先順序

1. %M2_HOME%/conf/settings.xml：全域 Profile，影響該機器所有使用者與專案。
2. ${user.home}/.m2/settings.xml：使用者級 Profile，影響該使用者所有專案。
3. pom.xml：專案級 Profile（最推薦），隨專案部署到倉庫，對下游建置可見。
4. profiles.xml（與 pom.xml 同目錄）：專案級 Profile，但不隨專案部署。

優先順序：pom.xml > profiles.xml > user settings.xml > global settings.xml。

注意：只有 repositories、pluginRepositories、properties 可在 settings.xml/profiles.xml 定義；其他類型（dependencies、plugins、build 等）必須在 pom.xml 定義。

Profile 啟動方式

1. 命令列顯式啟動

mvn groupId:artifactId:goal -P profileId-1,profileId-2

2. Settings.xml 持久啟動

<activeProfiles>
  <activeProfile>profile-1</activeProfile>
</activeProfiles>

3. 環境自動啟動

在 <activation> 區塊設定條件：

• JDK 版本：<jdk>1.8</jdk>（符合 1.8.x 即啟動）。
• 系統屬性存在：<property><name>debug</name></property> → mvn -Ddebug。
• 系統屬性值匹配：<property><name>env</name><value>test</value></property> → mvn -Denv=test。
• 作業系統：<os><name>Windows 10</name><family>Windows</family><arch>x86_64</arch><version>10.0</version></os>。
• 檔案缺失：<file><missing>target/generated-sources/...</missing></file>。

常見陷阱與解決方案

陷阱一：外部屬性導致可移植性失效

若 Profile 定義在 settings.xml，屬性（如 ${appserver.home}）僅存在於該使用者環境，其他開發者建置會失敗。

解決：將 Profile 移至 pom.xml，或利用父專案 pluginManagement 統一管理路徑，子專案繼承即可。

陷阱二：無 Profile 匹配導致屬性無法解析

若啟動條件為 -Denv=dev 或 dev-2，但執行時傳入 -Denv=production，則無 Profile 啟動，屬性 ${appserver.home} 無法解析。

解決：提供預設 Profile（無 activation 或 activeByDefault>true</activeByDefault>），或使用 mvn help:active-profiles 診斷。

查看當前啟動的 Profiles

mvn help:active-profiles
mvn help:active-profiles -Denv=dev
mvn help:active-profiles -P profileId

輸出範例：

The following profiles are active:
- appserverConfig-dev (source: pom)
- appserverConfig (source: settings.xml)

最佳實務建議

• 優先在 pom.xml 定義 Profile，確保可移植性。
• 善用 activation 自動適應環境，減少手動切換。
• 避免在 settings.xml 定義業務相關 Profile。
• 定期用 help:active-profiles 驗證生效狀態。