Maven 核心配置詳解：settings.xml 完整指南

前言

settings.xml 是 Maven 2 的全域性配置檔，定義了本地儲存庫、伺服器認證、鏡像站點、Proxy 代理、Profile 啟用等跨專案的共用設定。正確配置它對於團隊協作、依賴解析速度與建構環境一致性至關重要。本文將逐節剖析其核心元素與最佳實踐。

兩個 settings.xml 的角色

Maven 會合併兩者，使用者級配置優先覆蓋全域配置。

核心配置區段詳細解析

1. localRepository：本地儲存庫路徑

<localRepository>/data/maven-repo</localRepository>

預設為 ${user.home}/.m2/repository。建議團隊統一指向共享磁碟或快取目錄，避免重複下載。

2. offline：離線模式

<offline>true</offline>

設為 true 時 Maven 不會嘗試連線遠端儲存庫，適合無網路環境或已下載完所有依賴的建構機。

3. servers：伺服器認證資訊

對應 pom.xml 中 distributionManagement 的 repository id，避免密碼明文寫入 POM。

<servers>
  <server>
    <id>repo-local</id>
    <username>deployer</username>
    <password>secret123</password>
    <privateKey>${user.home}/.ssh/id_rsa</privateKey>
    <passphrase>keypass</passphrase>
    <filePermissions>664</filePermissions>
    <directoryPermissions>775</directoryPermissions>
  </server>
</servers>

關鍵點：id 必須與 POM 中儲存庫 id 完全一致；支援 SSH 金鑰認證；權限設定參考 Unix 權位碼。

4. mirrors：鏡像站點配置

加速依賴下載，將中央儲存庫導向內部或地區鏡像：

<mirrors>
  <mirror>
    <id>aliyun-maven</id>
    <name>Alibaba Cloud Maven Mirror</name>
    <url>https://maven.aliyun.com/repository/public</url>
    <mirrorOf>central</mirrorOf>
  </mirror>
</mirrors>

mirrorOf 可設為 central、*（所有）、external:*（非本地）等。

5. proxies：Proxy 代理設定

企業內網需透過 Proxy 存取外部儲存庫時必備：

<proxies>
  <proxy>
    <id>corp-proxy</id>
    <active>true</active>
    <protocol>http</protocol>
    <host>proxy.company.com</host>
    <port>8080</port>
    <username>proxyuser</username>
    <password>proxypass</password>
    <nonProxyHosts>*.company.com|localhost</nonProxyHosts>
  </proxy>
</proxies>

6. profiles：跨環境配置集合

Profile 封裝了 repositories、pluginRepositories、properties 等，需透過 activation 或 activeProfiles 啟用。

6.1 內部儲存庫定義

<profile>
  <id>internal-repo</id>
  <repositories>
    <repository>
      <id>repo-local</id>
      <name>Internal Repository</name>
      <url>https://192.168.0.2:8082/repo-local</url>
      <releases><enabled>true</enabled><updatePolicy>never</updatePolicy></releases>
      <snapshots><enabled>false</enabled></snapshots>
    </repository>
  </repositories>
  <pluginRepositories>
    <pluginRepository>
      <id>repo-local</id>
      <url>https://192.168.0.2:8082/repo-local</url>
      <releases><enabled>true</enabled></releases>
      <snapshots><enabled>false</enabled></snapshots>
    </pluginRepository>
  </pluginRepositories>
</profile>

說明：releases/snapshots 控制版本類型啟用；updatePolicy 設為 never 可減少檢查頻率。

6.2 Properties：屬性佔位符

支援五類來源：

• env.X：環境變數（如 env.JAVA_HOME）
• project.x：POM 元素（如 project.version）
• settings.x：settings.xml 元素
• Java System Properties：java.lang.System.getProperties()
• 使用者自訂：<property><name>my.prop</name><value>val</value></property>

6.3 Activation：自動啟用條件

<activation>
  <activeByDefault>false</activeByDefault>
  <jdk>1.8</jdk>
  <os>
    <name>Windows 10</name>
    <family>Windows</family>
    <arch>x86_64</arch>
    <version>10.0</version>
  </os>
  <property>
    <name>env.TEST_MODE</name>
    <value>true</value>
  </property>
  <file>
    <exists>${basedir}/config/dev.properties</exists>
    <missing>${basedir}/config/prod.properties</missing>
  </file>
</activation>

條件為「AND」關係，全部滿足才啟用。

7. activeProfiles：強制啟用的 Profile

<activeProfiles>
  <activeProfile>internal-repo</activeProfile>
  <activeProfile>jdk-1.8</activeProfile>
</activeProfiles>

無條件啟用指定 id 的 Profile，優先級高於 Activation。

最佳實踐建議

1. 版控全域設定：將 ${maven.home}/conf/settings.xml 納入版本控管，團隊成員同步更新。
2. 敏感資訊隔離：伺服器帳密、Proxy 密碼僅放於個人 ~/.m2/settings.xml，不可提交版控。
3. 善用 Profile 區分環境：定義 dev、test、prod 等 Profile，透過 -P 參數或環境變數切換。
4. 配置鏡像加速：中國大陸環境強烈建議配置阿里雲、騰訊雲等中央儲存庫鏡像。

結語

settings.xml 是 Maven 建構環境的「總開關」。深入理解其結構與優先順序，能讓團隊在依賴管理、部署認證、跨環境配置上遊刃有餘，避免「在我機器上能跑」的經典難題。