maven-settings.xml详解

前言

日常开发中，除了在pom.xml中配置单个项目的参数外，也可以在settings.xml中配置全局参数，下面来看看这些参数。更多信息请参考官方文档。

介绍

快速概览

settings.xml文件中的settings元素包含用于定义以各种方式配置Maven执行的值的元素，比如pom.xml，但是不应该绑定到任何特定项目或分发给用户。这些值包括本地存储库位置、备用远程存储库服务器和身份验证信息。

settings.xml文件可能存在两个位置:

• The Maven install: ${maven.home}/conf/settings.xml
• A user’s install: ${user.home}/.m2/settings.xml

前一个settings.xml也称为全局设置，后一个settings.xml称为用户设置。如果两个文件都存在，它们的内容将被合并，而用户特定的settings.xml将占主导地位。

提示:如果需要从头创建特定于用户的设置，最简单的方法是将Maven安装中的全局设置复制到${user.home}/.m2目录。Maven的默认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">
  <localRepository/>
  <interactiveMode/>
  <offline/>
  <pluginGroups/>
  <servers/>
  <mirrors/>
  <proxies/>
  <profiles/>
  <activeProfiles/>
</settings>

settings.xml的内容可以使用以下表达式进行插值:

1. ${user.home}和所有其他系统属性(自Maven 3.0以来)
2. ${env.HOME}等环境变量

注意，配置文件中定义的属性不能用于插值。

设置的细节

简单值

顶级settings元素的一半是简单值，表示一系列描述全职活动构建系统元素的值。

<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:该值是构建系统本地存储库的路径。默认值是${user.home}/.m2/repository。对于允许所有登录用户从公共本地存储库构建的主构建服务器，此元素特别有用。
• interactiveMode:如果Maven应该尝试与用户交互以获取输入，则为true，如果不是，则为false。默认值为true。
• offline:true如果该构建系统以脱机模式运行，则默认为false。对于由于网络设置或安全原因而无法连接到远程存储库的构建服务器，此元素非常有用。

插件组

这个元素包含一个pluginGroup元素的列表，每个元素包含一个groupId。当使用插件并且命令行中没有提供groupId时，会搜索列表。此列表自动包含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>

例如，给定上述设置，Maven命令行可以使用截断的命令执行org.eclipse.jetty:jetty-maven-plugin:run:

mvn jetty:run

服务器

用于下载和部署的存储库由POM的repositories和distributionManagement元素定义。但是，某些设置(如username和password)不应该与pom.xml一起分发。这种类型的信息应该存在于构建服务器的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元素相匹配的服务器的ID(不是作为登录用户的ID)。
• username, password:这些元素显示为一对，表示向该服务器进行身份验证所需的登录名和密码。
• privateKey, passphrase:与前两个元素一样，这对元素指定私钥的路径(默认为${user.home}/.ssh/id_dsa)和一个passphrase(如果需要的话)。passphrase和password元素将来可能会外部化，但目前它们必须在settings.xml文件中以明文设置。
• filePermissions, directoryPermissions:当在部署时创建存储库文件或目录时，这些是使用的权限。每个合法值是一个三位数，对应于*nix文件权限，例如664或775。

注意:如果使用私钥登录到服务器，请确保省略<password>元素。否则，该私钥将被忽略。

密码加密

一个新功能-服务器密码和口令加密已经增加到2.1.0+。详情请参阅此页

镜像

<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>

1. id, name:此镜像的唯一标识符和用户友好的名称。id用于区分镜像元素，并在连接到镜像时从<servers>部分中选择相应的凭据。
2. url:此镜像的基URL。构建系统将使用此URL连接到存储库，而不是原始存储库URL。
3. mirrorOf:作为镜像的存储库的id。例如，要指向Maven central存储库(https://repo.maven.apache.org/maven2/)的镜像，请将该元素设置为central。更高级的映射，如repo1、repo2或*,!inhouse也是可能的。这必须与镜像id不匹配。

想要更深入的介绍镜像，请阅读镜像设置指南。

代理

<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:此代理的唯一标识符。这用于区分proxy元素。
• active:如果此代理处于活动状态，则为true。这对于声明一组代理很有用，但是一次只能有一个是活动的。
• protocol, host, port:代理的protocol://host:port，被分割成离散的元素。
• username, password:这些元素以一对的形式出现，表示向此代理服务器进行身份验证所需的登录名和密码。
• nonProxyHosts:这是一个不应该被代理的主机列表。列表的分隔符是代理服务器的期望类型;上面的例子是管道分隔-逗号分隔也很常见。

配置文件

settings.xml中的profile元素是pom.xml profile元素的截断版本。它由activation、repositories、pluginRepositories和properties元素组成。profile元素只包含这四个元素，因为它们与构建系统作为一个整体(这是settings.xml文件的角色)有关，而不是单独的项目对象模型设置。

如果配置文件在settings中处于活动状态，那么它的值将覆盖POM或profiles.xml文件中ID相同的任何配置文件。

激活

激活是概要文件的关键。与POM的概要文件一样，概要文件的强大之处在于它只在特定情况下修改某些值的能力;这些环境是通过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>

当所有指定的条件都满足时，就会激活，尽管不是同时需要所有条件。

• jdk:activation在jdk元素中有一个内建的、以java为中心的检查。如果测试在与给定前缀匹配的jdk版本号下运行，则此操作将被激活。在上面的示例中，1.5.0_06将匹配。也支持范围。有关受支持范围的更多详细信息，请参见maven-enforcer-plugin。
• os:os元素可以定义一些操作系统特定的属性，如上所示。有关OS值的更多细节，请参见maven-enforcer-plugin。
• property:如果Maven检测到对应的name=value对的属性(可以在POM中通过${name}解除引用的值)，该profile将被激活。
• file:最后，一个给定的文件名可以通过文件的existence或missing来激活profile。

activation元素不是激活profile的唯一方式。settings.xml文件的activeProfile元素可以包含概要文件的id。它们也可以通过命令行激活，在-P标志后通过逗号分隔的列表(例如-P test)。

要查看在某个构建中将激活哪个配置文件，请使用maven-help-plugin。

mvn help:active-profiles

属性

Maven属性是值占位符，就像Ant中的属性一样。它们的值可以通过使用符号${X}在POM中的任何位置访问，其中X是属性。它们有五种不同的样式，都可以从settings.xml文件中访问:

1. env.X:将变量前缀为“env”。将返回shell的环境变量。例如,${env.PATH}包含$PATH环境变量(在Windows中为%PATH%)。
2. project.x:POM中的点(.)标记路径将包含相应元素的值。例如:<project><version>1.0</version></project>可通过${project.version}访问。
3. settings.x:settings.xml中的点(.)标记路径将包含相应元素的值。例如:<settings><offline>false</offline></settings>可以通过${settings.offline}访问。
4. Java系统属性:所有通过java.lang.System.getpProperties()访问的属性都可以作为POM属性使用，比如${java.home}。
5. x:在<properties />元素或外部文件中设置，可以使用${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>

如果该配置文件是活动的，则可以从POM访问${user.install}。

仓库

存储库是项目的远程集合，Maven使用它来填充构建系统的本地存储库。Maven正是通过这个本地存储库将其称为插件和依赖项。不同的远程存储库可能包含不同的项目，并且在活动的概要文件下，它们可能被搜索到匹配的发布或快照工件。

<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>
        ...
      </pluginRepositories>
      ...
    </profile>
  </profiles>
  ...
</settings>

• releases, snapshots:这些是针对每种类型的工件、发布或快照的策略。有了这两个集合，POM就可以在一个存储库中独立地修改每种类型的策略。例如，可能出于开发目的，人们决定只启用快照下载。
• enabled:该存储库是否为相应的类型(releases或snapshots)启用了true或false。
• updatePolicy:此元素指定更新应该尝试发生的频率。Maven将比较本地POM的时间戳(存储在存储库的Maven元数据文件中)和远程POM的时间戳。选项有:always、daily(默认)、interval:X(其中X是以分钟为单位的整数)或never。
• checksumPolicy:当Maven将文件部署到存储库时，它还将部署相应的校验和文件。您的选项是ignore、fail或在缺少或不正确的校验和时发出warn。
• layout:在上面对存储库的描述中，提到了它们都遵循一个通用的布局。这基本上是正确的。Maven 2有一个默认的存储库布局;然而,Maven 1.x有不同的布局。使用此元素指定它是default还是legacy。

插件仓库

存储库是两种主要类型的工件的所在地。第一种是用作其他工件依赖关系的工件。这些是驻留在central中的大部分工件。另一种类型的工件是插件。Maven插件本身就是一种特殊类型的工件。因此，插件存储库可能与其他存储库分离(尽管，我还没有听到有说服力的理由这么做)。在任何情况下，pluginRepositories元素块的结构都类似于repositories元素。每个pluginRepository元素都指定了一个Maven可以找到新插件的远程位置。

激活配置

<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元素，每个元素都有一个profile id值。任何定义为activeProfile的profile id都将是活动的，而不管任何环境设置。如果没有找到匹配的配置文件，什么也不会发生。例如，如果env-test是一个activeProfile，那么pom.xml(或具有相应id的profile.xml)中的profile将是活动的。如果没有找到这样的配置文件，那么执行将正常继续。

常用的设置

阿里云镜像

更多请参考仓库大全。下面是central仓和jcenter仓的聚合仓：

 <mirror>
	 <id>alimaven</id>
	 <mirrorOf>central,jcenter</mirrorOf>
	 <name>aliyun maven</name>
	 <url>https://maven.aliyun.com/repository/public</url>
 </mirror>

maven前20个仓库地址

<repositories>
 <repository>
  <id>top1</id>
  <name>Central</name>
  <url>https://repo1.maven.org/maven2/</url>
  <releases>
   <enabled>true</enabled>
  </releases>
  <snapshots>
   <enabled>true</enabled>
  </snapshots>
 </repository>
 <repository>
  <id>top2</id>
  <name>Sonatype</name>
  <url>https://oss.sonatype.org/content/repositories/releases/</url>
  <releases>
   <enabled>true</enabled>
  </releases>
  <snapshots>
   <enabled>true</enabled>
  </snapshots>
 </repository>
 <repository>
  <id>top3</id>
  <name>Spring Plugins</name>
  <url>https://repo.spring.io/plugins-release/</url>
  <releases>
   <enabled>true</enabled>
  </releases>
  <snapshots>
   <enabled>true</enabled>
  </snapshots>
 </repository>
 <repository>
  <id>top4</id>
  <name>Spring Lib M</name>
  <url>https://repo.spring.io/libs-milestone/</url>
  <releases>
   <enabled>true</enabled>
  </releases>
  <snapshots>
   <enabled>true</enabled>
  </snapshots>
 </repository>
 <repository>
  <id>top5</id>
  <name>Hortonworks</name>
  <url>https://repo.hortonworks.com/content/repositories/releases/</url>
  <releases>
   <enabled>true</enabled>
  </releases>
  <snapshots>
   <enabled>true</enabled>
  </snapshots>
 </repository>
 <repository>
  <id>top6</id>
  <name>Atlassian</name>
  <url>https://maven.atlassian.com/content/repositories/atlassian-public/</url>
  <releases>
   <enabled>true</enabled>
  </releases>
  <snapshots>
   <enabled>true</enabled>
  </snapshots>
 </repository>
 <repository>
  <id>top7</id>
  <name>JCenter</name>
  <url>https://jcenter.bintray.com/</url>
  <releases>
   <enabled>true</enabled>
  </releases>
  <snapshots>
   <enabled>true</enabled>
  </snapshots>
 </repository>
 <repository>
  <id>top8</id>
  <name>JBossEA</name>
  <url>https://repository.jboss.org/nexus/content/repositories/ea/</url>
  <releases>
   <enabled>true</enabled>
  </releases>
  <snapshots>
   <enabled>true</enabled>
  </snapshots>
 </repository>
 <repository>
  <id>top9</id>
  <name>JBoss Releases</name>
  <url>https://repository.jboss.org/nexus/content/repositories/releases/</url>
  <releases>
   <enabled>true</enabled>
  </releases>
  <snapshots>
   <enabled>true</enabled>
  </snapshots>
 </repository>
 <repository>
  <id>top10</id>
  <name>WSO2 Releases</name>
  <url>https://maven.wso2.org/nexus/content/repositories/releases/</url>
  <releases>
   <enabled>true</enabled>
  </releases>
  <snapshots>
   <enabled>true</enabled>
  </snapshots>
 </repository>
 <repository>
  <id>top11</id>
  <name>Spring Lib Release</name>
  <url>https://repo.spring.io/libs-release/</url>
  <releases>
   <enabled>true</enabled>
  </releases>
  <snapshots>
   <enabled>true</enabled>
  </snapshots>
 </repository>
 <repository>
  <id>top12</id>
  <name>WSO2 Public</name>
  <url>https://maven.wso2.org/nexus/content/repositories/public/</url>
  <releases>
   <enabled>true</enabled>
  </releases>
  <snapshots>
   <enabled>true</enabled>
  </snapshots>
 </repository>
 <repository>
  <id>top13</id>
  <name>IBiblio</name>
  <url>https://maven.ibiblio.org/maven2/</url>
  <releases>
   <enabled>true</enabled>
  </releases>
  <snapshots>
   <enabled>true</enabled>
  </snapshots>
 </repository>
 <repository>
  <id>top14</id>
  <name>XWiki Releases</name>
  <url>https://maven.xwiki.org/releases/</url>
  <releases>
   <enabled>true</enabled>
  </releases>
  <snapshots>
   <enabled>true</enabled>
  </snapshots>
 </repository>
 <repository>
  <id>top15</id>
  <name>Kotlin Dev</name>
  <url>https://dl.bintray.com/kotlin/kotlin-dev/</url>
  <releases>
   <enabled>true</enabled>
  </releases>
  <snapshots>
   <enabled>true</enabled>
  </snapshots>
 </repository>
 <repository>
  <id>top16</id>
  <name>Nuxeo</name>
  <url>https://maven-eu.nuxeo.org/nexus/content/repositories/public-releases/</url>
  <releases>
   <enabled>true</enabled>
  </releases>
  <snapshots>
   <enabled>true</enabled>
  </snapshots>
 </repository>
 <repository>
  <id>top17</id>
  <name>Clojars</name>
  <url>https://clojars.org/repo/</url>
  <releases>
   <enabled>true</enabled>
  </releases>
  <snapshots>
   <enabled>true</enabled>
  </snapshots>
 </repository>
 <repository>
  <id>top18</id>
  <name>Gradle Plugins</name>
  <url>https://plugins.gradle.org/m2/</url>
  <releases>
   <enabled>true</enabled>
  </releases>
  <snapshots>
   <enabled>true</enabled>
  </snapshots>
 </repository>
 <repository>
  <id>top19</id>
  <name>Geomajas</name>
  <url>http://maven.geomajas.org/</url>
  <releases>
   <enabled>true</enabled>
  </releases>
  <snapshots>
   <enabled>true</enabled>
  </snapshots>
 </repository>
 <repository>
  <id>top20</id>
  <name>Redhat GA</name>
  <url>https://maven.repository.redhat.com/ga/</url>
  <releases>
   <enabled>true</enabled>
  </releases>
  <snapshots>
   <enabled>true</enabled>
  </snapshots>
 </repository>
</repositories>