Maven settings.xml 文件詳解

概述

settings.xml 文件中的 settings 元素包含用于以各種方式配置 Maven 的元素(就像 pom.xml 文件一樣),但不應(yīng)捆綁到任何特定項(xiàng)目,或分發(fā)給受眾。其中包括本地存儲庫位置、備用遠(yuǎn)程存儲庫服務(wù)器和身份驗(yàn)證信息等值。

settings.xml 文件可能位于兩個(gè)位置:

  • ${maven.home}/conf/settings.xml。該文件為使用同一個(gè) Maven 安裝位置的用戶提供全局配置,可以通過在命令行使用 -gs 選項(xiàng)替換其默認(rèn)位置,比如 -gs /path/to/global/settings.xml;
  • ${user.home}/.m2/settings.xml。該文件為用戶特定的設(shè)置,可以通過在命令行使用 -s 選項(xiàng)替換其默認(rèn)位置,比如 -s /path/to/user/settings.xml。

如果兩個(gè)文件都存在,則它們的內(nèi)容將合并,如果某些相同的設(shè)置同時(shí)出現(xiàn)在兩個(gè)文件中,則以采用用戶特定的設(shè)置。

提示:如果需要從頭開始創(chuàng)建特定于用戶的設(shè)置,最簡單的方法是將全局設(shè)置的 ${maven.home}/conf/settings.xml 文件從 Maven 安裝目錄復(fù)制到 ${user.home}/.m2 目錄。Maven 默認(rèn)的 settings.xml 文件是一個(gè)帶有注釋和示例的模板,因此可以根據(jù)需要快速調(diào)整它。

以下是 settings 元素中的各頂級子元素的結(jié)構(gòu):

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
    <localRepository/>
    <interactiveMode/>
    <offline/>
    <pluginGroups/>
    <servers/>
    <mirrors/>
    <proxies/>
    <profiles/>
    <activeProfiles/>
</settings>

可以使用以下方式來覆蓋 settings.xml 的內(nèi)容:

  • ${user.home} 和所有其他系統(tǒng)屬性(自 Maven 3.0 以來);
  • ${env.HOME} 等,用于環(huán)境變量。

請注意,在 settings.xml 中的 profile 中定義的 property 不能用于覆蓋 settings.xml 中的內(nèi)容。

一些簡單設(shè)置

settings 元素中有一半是簡單設(shè)置(一個(gè) xml 元素搞定),這些值描述了整個(gè)構(gòu)建過程中一直激活的設(shè)置。

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
  <localRepository>${user.home}/.m2/repository</localRepository>
  <interactiveMode>true</interactiveMode>
  <offline>false</offline>
  ...
</settings>
  • localRepository:該元素值是默認(rèn)的本地倉庫路徑。默認(rèn)值為 ${user.home}/.m2/repository。對于 pom.xml 文件中為項(xiàng)目配置的所需依賴包,Maven 首先會根據(jù)依賴的三個(gè)坐標(biāo)檢查本地倉庫中是否存在對應(yīng)的依賴包,如果存在,則使用對應(yīng)的依賴包,如果不存在,則會自動連接遠(yuǎn)程 Maven 倉庫下載對應(yīng)的依賴包。這樣,可以大大減少下載依賴包的網(wǎng)絡(luò)流量。
  • interactiveMode:如果希望使 Maven 使用與用戶交互的方式來提示用戶輸入,則將該元素值設(shè)置為 true,否則設(shè)置為 false。默認(rèn)為 true。如果該元素值為 false, Maven 將使用一個(gè)可能基于其他設(shè)置的合理默認(rèn)值。
  • offline:如果希望 Maven 在離線模式下運(yùn)行,則將該元素值設(shè)置為 true,默認(rèn)為 false。該元素對于由于網(wǎng)絡(luò)設(shè)置或安全原因而無法連接到遠(yuǎn)程倉庫服務(wù)器的情形非常有用。

pluginGroups

pluginGroups 元素包含 pluginGroup 子元素的列表,每個(gè)元素都包含一個(gè) groupId。當(dāng)在命令行中使用形如 mvn prefix:goal 的命令且未提供插件的 groupId 時(shí),將搜索該列表。該列表自動包含了 org.apache.maven.pluginsorg.codehaus.mojo。

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
  ...
  <pluginGroups>
    <pluginGroup>org.eclipse.jetty</pluginGroup>
  </pluginGroups>
  ...
</settings>

例如,如果使用上述設(shè)置,可以在命令行中使用插件前綴來執(zhí)行完成的插件命令。比如 mvn jetty:run 等同于執(zhí)行 org.eclipse.jetty:jetty-maven-plugin:run 命令。

Servers

用于下載工件(artifact)和部署工件的倉庫由 POM 的 repositoriesdistributionManagement 元素定義。但是,某些設(shè)置(如用戶名和密碼)不應(yīng)與 pom.xml 一起分發(fā)。此類信息應(yīng)存在于構(gòu)建服務(wù)器的 settings.xml 中。

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
  ...
  <servers>
    <server>
      <id>server001</id>
      <username>my_login</username>
      <password>my_password</password>
      <privateKey>${user.home}/.ssh/id_dsa</privateKey>
      <passphrase>some_passphrase</passphrase>
      <filePermissions>664</filePermissions>
      <directoryPermissions>775</directoryPermissions>
      <configuration></configuration>
    </server>
  </servers>
  ...
</settings>
  • id:與 Maven 嘗試連接的倉庫或鏡像的 id 元素相匹配的服務(wù)器 id(而不是登錄用戶的 id)。
  • usernamepassword:這兩個(gè)元素成對出現(xiàn),表示向該服務(wù)器進(jìn)行身份驗(yàn)證所需的登錄名和密碼。
  • privateKey、passphrase:與前兩個(gè)元素一樣,這對元素指定私鑰的路徑(默認(rèn)值為 ${user.home}/.ssh/id_dsa)和口令(passphrase,如果需要)。passphrasepassword 元素將來可能會外部化,但目前它們必須在 settings.xml 文件中設(shè)置為純文本。
  • filePermissions、directoryPermissions:在部署時(shí)創(chuàng)建倉庫文件或目錄時(shí),這些是要使用的權(quán)限,該權(quán)限的法定值是一個(gè)三位數(shù)字,對應(yīng)于類 Unix 文件權(quán)限,例如 664 或 775。

注意:如果使用私鑰登錄服務(wù)器,請確保省略 <password> 元素。否則,該鍵將被忽略。

從 Maven 2.1.0+,可以對 passwordpassphrase 元素值進(jìn)行加密,詳情請參閱這里。

Mirrors

<mirrors> 元素指定從遠(yuǎn)程倉庫下載工件(artifact)時(shí)所使用的鏡像列表。它是這樣工作的:一個(gè) POM 可以聲明一個(gè)倉庫來解析某些工件。然而,這個(gè)倉庫有時(shí)可能會遇到流量過大的問題,所以將其副本復(fù)制到了好幾個(gè)地方。這個(gè)副本倉庫將有一個(gè)唯一的 id,因此我們可以為該副本倉庫創(chuàng)建一個(gè)鏡像引用,用作代替原先的下載站點(diǎn)。

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
  ...
  <mirrors>
    <mirror>
      <id>planetmirror.com</id>
      <name>PlanetMirror Australia</name>
      <url>http://downloads.planetmirror.com/pub/maven2</url>
      <mirrorOf>central</mirrorOf>
    </mirror>
  </mirrors>
  ...
</settings>
  • idname:該鏡像的唯一標(biāo)識符和用戶友好名稱。id 用于區(qū)分 mirror 元素,并在連接到鏡像時(shí)從 <servers> 元素中選擇相應(yīng)的憑據(jù)。
  • url:該鏡像的基本 url。Maven 將使用該 URL 連接到倉庫,而不是原始倉庫的 URL。
  • mirrorOf:這是鏡像倉庫的 id。例如,如果設(shè)置指向 Maven central 倉庫(https://repo.maven.apache.org/maven2/)的鏡像,將該元素設(shè)置為 central。更高級的映射, 如 repo1,repo2*,!inhouse。該元素值必須與 <mirror> 元素的 <id> 子元素值不匹配。

下面是幾個(gè)在國內(nèi)下載速度比較快的鏡像網(wǎng)站配置:

    <mirrors>
        <!-- 國內(nèi)的鏡像網(wǎng)站(下載速度應(yīng)該快上不少) -->
        <mirror>
            <id>huaweiyun</id>
            <mirrorOf>central</mirrorOf>
            <name>華為云公共倉庫</name>
            <url>https://mirrors.huaweicloud.com/repository/maven/</url>
        </mirror>
        <mirror>
            <id>aliyun</id>
            <mirrorOf>central</mirrorOf>
            <name>阿里云公共倉庫</name>
            <url>https://maven.aliyun.com/repository/public</url>
        </mirror>
        <mirror>
            <id>tencentyun</id>
            <mirrorOf>central</mirrorOf>
            <name>騰訊云公共倉庫</name>
            <url>http://mirrors.cloud.tencent.com/nexus/repository/maven-public/</url>
        </mirror>
        <!-- 國外的鏡像網(wǎng)站(下載速度可能較慢) -->
        <mirror>    
            <id>repo2</id>    
            <mirrorOf>central</mirrorOf>    
            <name>Maven Central Public Repository</name>    
            <url>http://repo2.maven.org/maven2/</url>    
        </mirror>
        <mirror>
            <id>ibiblio</id>    
            <mirrorOf>central</mirrorOf>    
            <name>ibiblio Repository</name>    
            <url>http://mirrors.ibiblio.org/pub/mirrors/maven2/</url>    
        </mirror>    
        <mirror>    
            <id>jboss-public-repository-group</id>    
            <mirrorOf>central</mirrorOf>    
            <name>JBoss Public Repository Group</name>    
            <url>http://repository.jboss.org/nexus/content/groups/public</url>    
        </mirror>  
        <mirror>    
            <id>JBossJBPM</id>   
          <mirrorOf>central</mirrorOf>   
          <name>JBossJBPM Repository</name>   
          <url>https://repository.jboss.org/nexus/content/repositories/releases/</url>  
        </mirror>  
    </mirrors>

Proxies

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
  ...
  <proxies>
    <proxy>
      <id>myproxy</id>
      <active>true</active>
      <protocol>http</protocol>
      <host>proxy.somewhere.com</host>
      <port>8080</port>
      <username>proxyuser</username>
      <password>somepassword</password>
      <nonProxyHosts>*.google.com|ibiblio.org</nonProxyHosts>
    </proxy>
  </proxies>
  ...
</settings>
  • id:此代理的唯一標(biāo)識符。這用于區(qū)分代理元素。
  • active:如果此代理處于激活狀態(tài),則將該元素值設(shè)置為 true。這在聲明了一組代理時(shí)非常有用,但一次只能有一個(gè)代理處于激活狀態(tài)。
  • protocolhost、port:代理 protocol://host:port,分散為三個(gè)元素。
  • username、password:這些元素成對出現(xiàn),表示向該代理服務(wù)器進(jìn)行身份驗(yàn)證所需的登錄名和密碼。
  • nonProxyHosts:不應(yīng)代理的目標(biāo)主機(jī)列表。該列表所用的分隔符是代理服務(wù)器的預(yù)期類型。上面的示例是管道符分隔的,逗號分隔也是常見的。

除非另有指定(通過系統(tǒng)屬性或命令行開關(guān)),否則將使用 proxies 元素中第一個(gè)激活的代理設(shè)置。

Profiles

settings.xml 文件中的 profile 元素是 pom.xml 文件中 profile 元素的縮減版本。settings.xml 文件中的 profile 元素由 activation、repositories、pluginRepositoriesproperties 這四個(gè)子元素組成,它們與構(gòu)建系統(tǒng)作為一個(gè)整體(這正是 settings.xml 文件所扮演的角色),而與單個(gè)項(xiàng)目的對象模型設(shè)置無關(guān)。

如果一個(gè) profilesettings 元素中處于激活狀態(tài),則其值將覆蓋 POM 或 profiles.xml 文件中的任何等效 ID 的 profile 設(shè)置。

與 POM 的 profile 一樣, settings 元素中的 profile 的好處在于它可以在特定情況下修改某些值,這通常是通過 activation 元素來指定的。

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
  ...
  <profiles>
    <profile>
      <id>test</id>
      <activation>
        <activeByDefault>false</activeByDefault>
        <jdk>1.5</jdk>
        <os>
          <name>Windows XP</name>
          <family>Windows</family>
          <arch>x86</arch>
          <version>5.1.2600</version>
        </os>
        <property>
          <name>mavenVersion</name>
          <value>2.0.3</value>
        </property>
        <file>
          <exists>${basedir}/file2.properties</exists>
          <missing>${basedir}/file1.properties</missing>
        </file>
      </activation>
      ...
    </profile>
  </profiles>
  ...
</settings>

當(dāng)所有指定的條件都滿足時(shí)才會激活,盡管并非所有條件都需要同時(shí)滿足。

  • jdkactivation 元素在 jdk 元素中有一個(gè)內(nèi)置的、以 Java 為中心的檢查。如果當(dāng)前運(yùn)行 Maven 的 JDK 版本與 jdk 元素中的 JDK 版本號前綴相匹配,則該 profile 將被激活。在上面的示例中,可以匹配 1.5.0_06。還支持范圍。有關(guān)支持范圍的更多詳細(xì)信息,請參閱 maven-enforcer-plugin 插件。
  • osos 元素可以定義上面所示的一些特定于操作系統(tǒng)的 property。有關(guān)操作系統(tǒng)值的更多詳細(xì)信息,請參閱 maven-enforcer-plugin 插件。
  • property:如果 Maven 檢測到對應(yīng)的 name=value 的 property(可以在 POM 文件中使用 ${name} 來間接引用該 property 的值),該 profile 將被激活。
  • file:最后,一個(gè)給定的文件名可能通過文件的存在或丟失來激活 profile。

activation 元素不是激活 profile 的唯一方式。settings.xml 文件的 activeProfile 元素可能包含 profile 的 id。它們也可以通過在命令行中的 -P 標(biāo)志后跟一個(gè)逗號分隔列表來顯式激活某個(gè) profile(例如 -P test)。

要查看哪個(gè) profile 將在特定構(gòu)建中激活,請使用 maven-help-plugin 插件。

mvn help:active-profiles

Properties

Maven 中的 property 是值占位符,就像 Ant 中的 property 一樣,它們的值可以通過使用諸如 ${X} 的形式在 POM 中的任何位置訪問名為 X property 的值。它們有五種不同的樣式,都可以從 settings.xml 文件訪問:

  • env.X:在變量前面加上 env. 將返回 shell 的環(huán)境變量。例如,${env.PATH} 包含 $path 環(huán)境變量(在 Windows 中對應(yīng)的環(huán)境變量為 %PATH% );
  • project.x:POM 中以點(diǎn)號 . 表示的路徑將包含相應(yīng)元素的值。例如:<project><version>1.0</version></project> 可以通過 ${project.version} 訪問;
  • settings.xsettings.xml 中以點(diǎn)號 . 表示的路徑將包含相應(yīng)元素的值。例如:<settings><offline>false</offline></settings> 可通過${settings.offline} 訪問。
  • Java 系統(tǒng)屬性:通過 java.lang.System.getProperties() 訪問的所有 property 都可以作為 POM 的 property 使用,例如 ${java.home}。
  • x:在 <properties/> 元素或外部文件中設(shè)置,該值可以用作 ${someVar}。
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
  ...
  <profiles>
    <profile>
      ...
      <properties>
        <user.install>${user.home}/our-project</user.install>
      </properties>
      ...
    </profile>
  </profiles>
  ...
</settings>

如果該 profile 處于激活狀態(tài),則可以從 POM 文件訪問 ${user.install} property。

Repositories

倉庫是項(xiàng)目的遠(yuǎn)程集合,Maven 可以使用這些遠(yuǎn)程項(xiàng)目填充構(gòu)建系統(tǒng)的本地倉庫,Maven 將其 plugindependency 存儲在這個(gè)本地倉庫中。不同的遠(yuǎn)程倉庫可能包含不同的項(xiàng)目,在某個(gè)激活的 profile 下,可以搜索這些遠(yuǎn)程倉庫來查找匹配的 release 或 snapshot 的工件。

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
  ...
  <profiles>
    <profile>
      ...
      <repositories>
        <repository>
          <id>codehausSnapshots</id>
          <name>Codehaus Snapshots</name>
          <releases>
            <enabled>false</enabled>
            <updatePolicy>always</updatePolicy>
            <checksumPolicy>warn</checksumPolicy>
          </releases>
          <snapshots>
            <enabled>true</enabled>
            <updatePolicy>never</updatePolicy>
            <checksumPolicy>fail</checksumPolicy>
          </snapshots>
          <url>http://snapshots.maven.codehaus.org/maven2</url>
          <layout>default</layout>
        </repository>
      </repositories>
      <pluginRepositories>
        <pluginRepository>
          <id>myPluginRepo</id>
          <name>My Plugins repo</name>
          <releases>
            <enabled>true</enabled>
          </releases>
          <snapshots>
            <enabled>false</enabled>
          </snapshots>
          <url>https://maven-central-eu....com/maven2/</url>
        </pluginRepository>
      </pluginRepositories>
      ...
    </profile>
  </profiles>
  ...
</settings>
  • releases、snapshots:有了這兩個(gè)元素,POM 就可以在對應(yīng)的倉庫中獨(dú)立地選擇使用 releasesnapshot 類型的工件(artifact)。例如,開發(fā)人員可能出于開發(fā)目的僅啟用 Snapshot 下載。
  • enabled:對于該倉庫是否已為相應(yīng)類型(版本或快照)啟用,為 true 或 false。
  • updatePolicy:該元素指定更新發(fā)生的頻率。Maven 將本地 POM 的時(shí)間戳(存儲在倉庫的 Maven 元數(shù)據(jù)文件中)與遠(yuǎn)程 POM 進(jìn)行比較。該元素值可以為:always、daily(默認(rèn))、interval:X(其中,其中 X 是以分鐘為單位的整數(shù))、或 never。
  • checksumPolicy:當(dāng) Maven 將文件部署到倉庫時(shí),它也會部署相應(yīng)的校驗(yàn)和文件。當(dāng)丟失校驗(yàn)和文件或校驗(yàn)和文件錯(cuò)誤時(shí),可以選擇 ignore、fail、warn。
  • layout:上面對倉庫的描述中提到倉庫都遵循一個(gè)通用的布局,這基本上是正確的。Maven 2 的倉庫有一個(gè)默認(rèn)布局;然而,Maven 1.x 有一個(gè)不同的布局。使用該元素可以指定 default 布局(Maven 2 的布局)還是 legacy 布局(Maven 1.x 的布局)。

Plugin Repositories

倉庫是兩種主要類型工件的所在地:

  • 第一種是用作依賴(dependency)的工件,Maven 中央倉庫中的大多數(shù)工件都是這種類型;
  • 另一類工件是插件(plugin)。Maven 插件本身就是一種特殊類型的工件。正因?yàn)槿绱?,插件倉庫可能與其他倉庫分離(盡管如此,一般是不會將插件倉庫和其他倉庫分開的)。

在任何情況下,pluginRepositories 元素的結(jié)構(gòu)都類似于 repositories 元素。pluginRepository 元素都指定了 Maven 可以在其中找到插件的遠(yuǎn)程地址。

Active Profiles

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
  ...
  <activeProfiles>
    <activeProfile>env-test</activeProfile>
  </activeProfiles>
</settings>

settings.xml 元素的最后一塊是 activeProfiles 元素。這包含一組 activeProfile 元素,每個(gè) activeProfile 元素都有一個(gè) profileid 值。無論環(huán)境設(shè)置如何,定義為 activeProfile 的任何 profile id 都將處于激活狀態(tài)。如果沒有找到匹配的 profile,則什么也不會發(fā)生。例如,如果 env-testactiveProfile,則 pom.xml(或 profile.xml)中具有相應(yīng) idprofile 將處于激活狀態(tài)。如果沒有找到這樣的 profile,則會忽略并繼續(xù)執(zhí)行其他配置。

?著作權(quán)歸作者所有,轉(zhuǎn)載或內(nèi)容合作請聯(lián)系作者
【社區(qū)內(nèi)容提示】社區(qū)部分內(nèi)容疑似由AI輔助生成,瀏覽時(shí)請結(jié)合常識與多方信息審慎甄別。
平臺聲明:文章內(nèi)容(如有圖片或視頻亦包括在內(nèi))由作者上傳并發(fā)布,文章內(nèi)容僅代表作者本人觀點(diǎn),簡書系信息發(fā)布平臺,僅提供信息存儲服務(wù)。

相關(guān)閱讀更多精彩內(nèi)容

  • 一、配置分級 首先需要了解的是Maven配置文件以及配置方式的分級,才能做到我們自己在日常開發(fā)配置中靈活使用。根據(jù)...
    老貓燒須閱讀 15,052評論 1 12
  • 概要 settings.xml有什么用? 如果在Eclipse中使用過Maven插件,想必會有這個(gè)經(jīng)驗(yàn):配置set...
    靜默虛空閱讀 19,571評論 2 32
  • maven運(yùn)行時(shí)的配置文件settings.xml 安裝位置 全局配置:${maven_home}/config/...
    Elf_樂易閱讀 5,612評論 0 1
  • 本文是對https://maven.apache.org/settings.html的翻譯和總結(jié) 介紹 快速概覽 ...
    AlanSun2閱讀 9,305評論 0 4
  • 16宿命:用概率思維提高你的勝算 以前的我是風(fēng)險(xiǎn)厭惡者,不喜歡去冒險(xiǎn),但是人生放棄了冒險(xiǎn),也就放棄了無數(shù)的可能。 ...
    yichen大刀閱讀 7,867評論 0 4

友情鏈接更多精彩內(nèi)容