Maven settings.xml 文件详解

概述

settings.xml 文件中的 settings 元素包含用于以各种方式配置 Maven 的元素（就像 pom.xml 文件一样），但不应捆绑到任何特定项目，或分发给受众。其中包括本地存储库位置、备用远程存储库服务器和身份验证信息等值。

settings.xml 文件可能位于两个位置：

${maven.home}/conf/settings.xml。该文件为使用同一个 Maven 安装位置的用户提供全局配置，可以通过在命令行使用 -gs 选项替换其默认位置，比如 -gs /path/to/global/settings.xml；
${user.home}/.m2/settings.xml。该文件为用户特定的设置，可以通过在命令行使用 -s 选项替换其默认位置，比如 -s /path/to/user/settings.xml。

如果两个文件都存在，则它们的内容将合并，如果某些相同的设置同时出现在两个文件中，则以采用用户特定的设置。

提示：如果需要从头开始创建特定于用户的设置，最简单的方法是将全局设置的 ${maven.home}/conf/settings.xml 文件从 Maven 安装目录复制到 ${user.home}/.m2 目录。Maven 默认的 settings.xml 文件是一个带有注释和示例的模板，因此可以根据需要快速调整它。

以下是 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/><interactiveMode/><offline/><pluginGroups/><servers/><mirrors/><proxies/><profiles/><activeProfiles/>
</settings>

可以使用以下方式来覆盖 settings.xml 的内容：

${user.home} 和所有其他系统属性（自 Maven 3.0 以来）；
${env.HOME} 等，用于环境变量。

请注意，在 settings.xml 中的 profile 中定义的 property 不能用于覆盖 settings.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"><localRepository>${user.home}/.m2/repository</localRepository><interactiveMode>true</interactiveMode><offline>false</offline>...
</settings>

localRepository：该元素值是默认的本地仓库路径。默认值为 ${user.home}/.m2/repository。对于 pom.xml 文件中为项目配置的所需依赖包，Maven 首先会根据依赖的三个坐标检查本地仓库中是否存在对应的依赖包，如果存在，则使用对应的依赖包，如果不存在，则会自动连接远程 Maven 仓库下载对应的依赖包。这样，可以大大减少下载依赖包的网络流量。
interactiveMode：如果希望使 Maven 使用与用户交互的方式来提示用户输入，则将该元素值设置为 true，否则设置为 false。默认为 true。如果该元素值为 false， Maven 将使用一个可能基于其他设置的合理默认值。
offline：如果希望 Maven 在离线模式下运行，则将该元素值设置为 true，默认为 false。该元素对于由于网络设置或安全原因而无法连接到远程仓库服务器的情形非常有用。

pluginGroups

pluginGroups 元素包含 pluginGroup 子元素的列表，每个元素都包含一个 groupId。当在命令行中使用形如 mvn prefix:goal 的命令且未提供插件的 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>

例如，如果使用上述设置，可以在命令行中使用插件前缀来执行完成的插件命令。比如 mvn jetty:run 等同于执行 org.eclipse.jetty:jetty-maven-plugin:run 命令。

Servers

用于下载工件（artifact）和部署工件的仓库由 POM 的 repositories 和 distributionManagement 元素定义。但是，某些设置（如用户名和密码）不应与 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：在部署时创建仓库文件或目录时，这些是要使用的权限，该权限的法定值是一个三位数字，对应于类 Unix 文件权限，例如 664 或 775。

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

从 Maven 2.1.0+，可以对 password 和 passphrase 元素值进行加密，详情请参阅这里。

Mirrors

<mirrors> 元素指定从远程仓库下载工件（artifact）时所使用的镜像列表。它是这样工作的：一个 POM 可以声明一个仓库来解析某些工件。然而，这个仓库有时可能会遇到流量过大的问题，所以将其副本复制到了好几个地方。这个副本仓库将有一个唯一的 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">...<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：该镜像的唯一标识符和用户友好名称。id 用于区分 mirror 元素，并在连接到镜像时从 <servers> 元素中选择相应的凭据。
url：该镜像的基本 url。Maven 将使用该 URL 连接到仓库，而不是原始仓库的 URL。
mirrorOf：这是镜像仓库的 id。例如，如果设置指向 Maven central 仓库（https://repo.maven.apache.org/maven2/）的镜像，将该元素设置为 central。更高级的映射，如 repo1,repo2 或 *,!inhouse。该元素值必须与 <mirror> 元素的 <id> 子元素值不匹配。

下面是几个在国内下载速度比较快的镜像网站配置：

 <mirrors><!-- 国内的镜像网站（下载速度应该快上不少） --><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><!-- 国外的镜像网站（下载速度可能较慢） --><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：此代理的唯一标识符。这用于区分代理元素。
active：如果此代理处于激活状态，则将该元素值设置为 true。这在声明了一组代理时非常有用，但一次只能有一个代理处于激活状态。
protocol、host、port：代理 protocol://host:port，分散为三个元素。
username、password：这些元素成对出现，表示向该代理服务器进行身份验证所需的登录名和密码。
nonProxyHosts：不应代理的目标主机列表。该列表所用的分隔符是代理服务器的预期类型。上面的示例是管道符分隔的，逗号分隔也是常见的。

除非另有指定（通过系统属性或命令行开关），否则将使用 proxies 元素中第一个激活的代理设置。

Profiles

settings.xml 文件中的 profile 元素是 pom.xml 文件中 profile 元素的缩减版本。settings.xml 文件中的 profile 元素由 activation、repositories、pluginRepositories 和 properties 这四个子元素组成，它们与构建系统作为一个整体（这正是 settings.xml 文件所扮演的角色），而与单个项目的对象模型设置无关。

如果一个 profile 在 settings 元素中处于激活状态，则其值将覆盖 POM 或 profiles.xml 文件中的任何等效 ID 的 profile 设置。

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

当所有指定的条件都满足时才会激活，尽管并非所有条件都需要同时满足。

jdk：activation 元素在 jdk 元素中有一个内置的、以 Java 为中心的检查。如果当前运行 Maven 的 JDK 版本与 jdk 元素中的 JDK 版本号前缀相匹配，则该 profile 将被激活。在上面的示例中，可以匹配 1.5.0_06。还支持范围。有关支持范围的更多详细信息，请参阅 maven-enforcer-plugin 插件。
os：os 元素可以定义上面所示的一些特定于操作系统的 property。有关操作系统值的更多详细信息，请参阅 maven-enforcer-plugin 插件。
property：如果 Maven 检测到对应的 name=value 的 property（可以在 POM 文件中使用 ${name} 来间接引用该 property 的值），该 profile 将被激活。
file：最后，一个给定的文件名可能通过文件的存在或丢失来激活 profile。

activation 元素不是激活 profile 的唯一方式。settings.xml 文件的 activeProfile 元素可能包含 profile 的 id。它们也可以通过在命令行中的 -P 标志后跟一个逗号分隔列表来显式激活某个 profile（例如 -P test）。

要查看哪个 profile 将在特定构建中激活，请使用 maven-help-plugin 插件。

mvn help:active-profiles

Properties

Maven 中的 property 是值占位符，就像 Ant 中的 property 一样，它们的值可以通过使用诸如 ${X} 的形式在 POM 中的任何位置访问名为 X property 的值。它们有五种不同的样式，都可以从 settings.xml 文件访问：

env.X：在变量前面加上 env. 将返回 shell 的环境变量。例如，${env.PATH} 包含 $path 环境变量（在 Windows 中对应的环境变量为 %PATH% ）；
project.x：POM 中以点号 . 表示的路径将包含相应元素的值。例如：<project><version>1.0</version></project> 可以通过 ${project.version} 访问；
settings.x：settings.xml 中以点号 . 表示的路径将包含相应元素的值。例如：<settings><offline>false</offline></settings> 可通过${settings.offline} 访问。
Java 系统属性：通过 java.lang.System.getProperties() 访问的所有 property 都可以作为 POM 的 property 使用，例如 ${java.home}。
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>

如果该 profile 处于激活状态，则可以从 POM 文件访问 ${user.install} property。

Repositories

仓库是项目的远程集合，Maven 可以使用这些远程项目填充构建系统的本地仓库，Maven 将其 plugin 和 dependency 存储在这个本地仓库中。不同的远程仓库可能包含不同的项目，在某个激活的 profile 下，可以搜索这些远程仓库来查找匹配的 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：有了这两个元素，POM 就可以在对应的仓库中独立地选择使用 release 或 snapshot 类型的工件（artifact）。例如，开发人员可能出于开发目的仅启用 Snapshot 下载。
enabled：对于该仓库是否已为相应类型（版本或快照）启用，为 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 布局（Maven 2 的布局）还是 legacy 布局（Maven 1.x 的布局）。

Plugin Repositories

仓库是两种主要类型工件的所在地：

第一种是用作依赖（dependency）的工件，Maven 中央仓库中的大多数工件都是这种类型；
另一类工件是插件（plugin）。Maven 插件本身就是一种特殊类型的工件。正因为如此，插件仓库可能与其他仓库分离（尽管如此，一般是不会将插件仓库和其他仓库分开的）。

在任何情况下，pluginRepositories 元素的结构都类似于 repositories 元素。pluginRepository 元素都指定了 Maven 可以在其中找到插件的远程地址。

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 元素，每个 activeProfile 元素都有一个 profile 的 id 值。无论环境设置如何，定义为 activeProfile 的任何 profile id 都将处于激活状态。如果没有找到匹配的 profile，则什么也不会发生。例如，如果 env-test 是 activeProfile，则 pom.xml（或 profile.xml）中具有相应 id 的 profile 将处于激活状态。如果没有找到这样的 profile，则会忽略并继续执行其他配置。