概述
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.plugins 和 org.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 的 repositories 和 distributionManagement 元素定義。但是,某些設(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)。 -
username、password:這兩個(gè)元素成對出現(xiàn),表示向該服務(wù)器進(jìn)行身份驗(yàn)證所需的登錄名和密碼。 -
privateKey、passphrase:與前兩個(gè)元素一樣,這對元素指定私鑰的路徑(默認(rèn)值為${user.home}/.ssh/id_dsa)和口令(passphrase,如果需要)。passphrase和password元素將來可能會外部化,但目前它們必須在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+,可以對 password 和 passphrase 元素值進(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>
-
id、name:該鏡像的唯一標(biāo)識符和用戶友好名稱。id 用于區(qū)分mirror元素,并在連接到鏡像時(shí)從<servers>元素中選擇相應(yīng)的憑據(jù)。 -
url:該鏡像的基本 url。Maven 將使用該 URL 連接到倉庫,而不是原始倉庫的 URL。 -
mirrorOf:這是鏡像倉庫的id。例如,如果設(shè)置指向 Mavencentral倉庫(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)。 -
protocol、host、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、pluginRepositories 和 properties 這四個(gè)子元素組成,它們與構(gòu)建系統(tǒng)作為一個(gè)整體(這正是 settings.xml 文件所扮演的角色),而與單個(gè)項(xiàng)目的對象模型設(shè)置無關(guān)。
如果一個(gè) profile 在 settings 元素中處于激活狀態(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í)滿足。
-
jdk:activation元素在jdk元素中有一個(gè)內(nèi)置的、以 Java 為中心的檢查。如果當(dāng)前運(yùn)行 Maven 的 JDK 版本與jdk元素中的 JDK 版本號前綴相匹配,則該profile將被激活。在上面的示例中,可以匹配 1.5.0_06。還支持范圍。有關(guān)支持范圍的更多詳細(xì)信息,請參閱 maven-enforcer-plugin 插件。 -
os:os元素可以定義上面所示的一些特定于操作系統(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.x:settings.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 將其 plugin 和 dependency 存儲在這個(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ú)立地選擇使用release或snapshot類型的工件(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è) profile 的 id 值。無論環(huán)境設(shè)置如何,定義為 activeProfile 的任何 profile id 都將處于激活狀態(tài)。如果沒有找到匹配的 profile,則什么也不會發(fā)生。例如,如果 env-test 是 activeProfile,則 pom.xml(或 profile.xml)中具有相應(yīng) id 的 profile 將處于激活狀態(tài)。如果沒有找到這樣的 profile,則會忽略并繼續(xù)執(zhí)行其他配置。