setting.xml作为Maven最重要的配置文件，其中存在诸多的配置项，本文手工翻译了Apache官方Maven站点对于setting.xml的配置的页面，帮助初学者更简单了解该配置文件的用法和作用。

1. 简介

1.1 快速概述

setting.xml的顶级节点是<code>settings</code>元素，它包含很多子元素用来定义Maven不同的运行方式所需要的值，和<code>pom.xml</code>类似，但是不应该被绑定到特定的项目或者发布给用户。这些子元素包括本地仓库位置、远程仓库的替代服务和一些认证信息等等。
<code>settings.xml</code>一般存在于两个位置：

• Maven安装的主目录： <code>$MAVEN_HOME/conf/settings.xml</code>
• 用户主目录： <code>$USER_HOME/.m2/settings.xml</code>
  第一个<code>setting.xml</code>也被称为全局配置文件，而第二个则称为用户配置。当然，如果两个文件同时存在，他们的内容将会合并，用户配置将会覆盖全局配置。

小建议：如果你需要从头开始创建指定用户的配置，最简单的方法是将全局配置文件从你的Maven安装目录复制到你的用户目录下的.m2目录下面。Maven默认的<code>settings.xml</code>是一个带有注释和事例的模板，所以你可以很轻松地微调来满足你的需要。

下面是一个位于<code>settings</code>之下的顶级元素的概览：

settings.xml的一级元素

<code>settings.xml</code>的内容可以通过一下表达式覆盖：

1. <code>${user.home}</code>和其它系统属性(Maven3.0以后)

2. <code>${env.HOME}</code>例如环境变量

2. 配置详情

2.1 简值

在<code>settings</code>中超过一半的元素使用简单的值去代表一个用来描述被激活的构建系统的元素的范围。

使用简单的值来配置settings.xml

• localRepository：这个值是构建系统本地仓库的一个路径。默认的值是<code>${user.home}/.m2/repository</code>。这个元素对于一个允许所有登陆用户从共同的本地仓库中构建的主要服务器来说非常有用。
• interactiveMode：<code>true</code>代表Maven需要尝试和用户的输入进行交互，<code>false</code>则不会，默认是<code>true</code>。
• usePluginRegistry：<code>true</code>表示Maven应该使用<code>${user.home}/.m2/plugin-regisry.xml</code>文件去管理Maven插件版本，默认是<code>false</code>。
• offline：<code>true</code>绑定的构建系统应该在离线模式下操作，默认是<code>false</code>。这个元素对于不能连接远程仓库务器亦或者是由于网络限制或者是安全原因的构建服务器非常有用。

2.2 插件组

这个元素包括一系列的<code>pluginGroup</code>元素，每一个子元素都包含一个groupId。当一个插件被使用，并且
没有在命令行上提供的时候，插件组列表就会被查找。这个列表自动包含<code>org.apache.maven.plugins</code>和<code>org.codehaus.mojo</code>。

pluginGroup

例如，如果配置成上图所示的样子，则可以执行使用简写去执行<code>org.mortbay.jetty:jetty-maven-plugin:run</code>。

<code>mvn jetty:run</code>

2.3 服务器

下载和部署的仓库被POM里面的<code>repositories</code>和<code>distributionManagement</code>所指定。然而，确定的用户名和密码不应该和<code>pom.xml</code>一起被发布。这一类型的信息存在于构建服务器的<code>settings.xml</code>中。

2.3.1 密码加密

一个新的特性-服务器密码和密码短语加密已经被添加到Maven2.1.0以上的版本。查看详细的内容。

servers配置范例

• id：这个是服务器的ID(不是用户登陆的名字)，Maven会根据这个ID去匹配响应的仓库和镜像去连接。
• username，password:和之前的两个元素类似，这一对指明了私钥的路径(默认是<code>${user.home}/.ssh/id_dsa</code>)和<code>passphrase</code>，当然如果需要的话。这两个元素在未来可能被扩展，但是现在他们必须被设置成文本在<code>settings.xml</code>文件中
• filePermissions,directoryPermissions:当一个仓库文件或者部署时创建的目录这些权限将被使用到。合法的数值是一个三位数字代表相应的l*nix文件权限，例如664或者是775。

注意：如果你使用私钥去登陆服务器，确定你省略了<code>password</code>元素。否则，这个元素将会被忽略。

2.4 镜像

镜像的配置样例

• id, name: 分别代表当前镜像的唯一标识符和名字。<code>id</code>用来区分不同的<code>mirror</code>元素和用来从<code>server</code>中取得对应的凭据当连接镜像的时候。
• url: 镜像的url地址。构建系统将会使用这个URL连接仓库。
• mirrOf 镜像的所属的仓库的<code>id</code>。例如，为了让镜像指向Maven的<code>central</code>仓库(<code>http://repo.maven.apache.org/maven2/</code>)。可以将<code>mirrorOf</code>设置为<code>central</code>。更多高级的映射像<code>repo1,repo2</code>或者<code>*,!inhouse</code>也是可以的，但是必须不能和<code>id</code>匹配。

如果需要更深一步的了解镜像的配置，可以查阅[Guide to Mirror Settings.

2.5 代理

代理的配置范例

• id: 这个代理的唯一标识。用来区分不同的<code>proxy</code>。
• active: 当前代理是否被激活。声明了一个代理集合，但是在同一时间只有一个在使用。
• protocol, host, port: 代理的地址<code>protocol://host:port</code>，可以使用不连续的元素区分
• username, password: 这两个元素作为一对用于声明登陆需要验证密码的代理。
• nnProxyHosts: 列出不许要通过代理访问的域名。多个域名的分隔符取决于代理的类型，上图所示的逗号分隔符是常用的一中。

2.6 简介

<code>settings.xml</code>中的<code>profile</code>是<code>pom.xml</code><code>profile</code>的简写版本。它由<code>activation</code>，<code>repositories</code>,<code>pluginRepositories</code>和<code>properties</code>元素。<code>profile</code>元素只包括这四个元素因为它们只关心构建系统，而不关心单独的项目对象模型配置。
如果一个简介从<code>settings</code>中激活。它的值将会覆盖任何在POM中相同id的简介或者是<code>profiles.xml</code>文件。

2.6.1 激活

激活是简介的key。和POM里面的简介一样，简介的作用来自于它在确定的情况下修改一些值的能力。这些情形会被<code>activation</code>元素指定。

Activation配置范例

虽然很多条件不会在同一时刻满足，但是激活会在所有指定的标准都符合时执行。

• jdk: <code>activation</code>有一个内建的，Java为中心的校验在<code>jdk</code>元素中。当测试在符合Jdk版本前缀的环境中执行时，会生效。在上面的范例中，<code>1.5.0_06</code>是符合的条件。匹配一个范围在Maven2.1以后也是支持的。查看 maven-enforcer-plugin去了解更多关于范围查询的文档。
• os: 这个元素定义了一些特定的操作系统的属性。查看 maven-enforcer-plugin去了解这些值的更多信息。
• property: 如果Maven发现了一个属性(一个可以在POM中通过引用相应的<code>name=value</code>对的<code>${name}</code>值)。
• file: 最后，一个指定的文件名字将会通过文件的<code>existence</code>激活<code>profile</code>，或者是<code>missing</code>

<code>activation</code>元素不是唯一能够激活<code>profile</code>的方式。<code>settings.xml</code>文件的<code>activeProfile</code>元素也包含了简介的<code>id</code>。它也可以通过命令行中位于<code>-P</code>标识之后的的逗号分割符被显示地激活(例如<code>-P test</code>)。
为了查看那些简介能够在当期构建系统中被激活，可以使用<code>maven-help-plugin</code>。

查看当前系统的激活简介

2.6.2 属性

Maven的属性是值占位符，想Ant中的属性一样。他们的值可以在POM中的任何地方通过使用标记<code>${X}</code>取到。有5种形式在<code>settings.xml</code>文件中取到值。

1. <code>env.X</code>: 以env为前缀的变量将会返回shell的环境变量。例如，<code>${env.PATH}</code>包含了$PATH环境变量在*nix或者是%PATH%在Windows中。
2. project.x: 标记在POM下面的对应元素的值。例如：<code><project><version>1.0</version></project></code>可以通过<code>${project.version}</code>访问。
3. <code>settingx.x</code>: 标记在<code>settings</code>里面相应元素的数值。例如：<code><settings><offline>false</offline></settings></code>可以通过<code>${settings.offline}</code>访问。
4. Java系统属性：所有的可以通过<code>java.lang.System.getProperties()</code>取得的系统属性都可作为POM的属性，例如<code>${java.home}</code>
5. <code>x</code>: 在<properties/>元素中或者是外置文件，这些值可以通过<code>${someVar}</code>访问。

在POM中访问${user.install}

2.6.2 仓库

仓库是Maven用来导入构建系统本地仓库的远程项目的集合。Maven在这个仓库中取得插件和依赖。不同的远程仓库包含不同的项目，在激活的<code>profile</code>中，仓库会被查询匹配相应的发布或者是快照版本的构件。

仓库的配置范例

• release, snapshot: 这是构建的两种不同的类型，发布版或者是快照版。通过这两个配置，POM在一个仓库中任意修改依赖的类型。例如，只允许通过快照仓库下载，为了方便开发。
• enbaled: <code>true</code>或者<code>false</code>决定当前仓库是否对发布版或者是快照版类型的构件有效。
• updatePolicy: 这个元素指定了多久更新一次。Maven会去比较本地的POM的时间戳(存储在仓库的maven元数据中)。
• checksumPolicy: 当Maven部署文件到仓库，它也会把相应的校验和文件部署上去。对于丢失或者不正确的校验和你的可选项是<code>ignore</code>,<code>fail</code>或者是<code>warn</code>。
• layout: 在上面展示的仓库中，它们都遵守一个通用的布局。这是非常正确的。Maven2对于它的仓库有一个默认的布局。然而，Maven1.x过去有一个不同的布局。使用这个元素去指定<code>default</code>或者是<code>legacy</code>布局。

2.6.3 插件仓库

仓库是主要的两种类型的构件的存放位置。第一种是作为其它构件依赖的构件。大部分存在于中央仓库的构件都是这种类型。另外一种类型是插件。Maven插件自身是一种特殊的构件。鉴于此，Maven的插件仓库和其它仓库是分开的。不管怎么说，<code>pluginRepositories</code>元素块的结构和<code>repositories</code>的结构相似。每个<code>pluginRepository</code>元素指定了一个远程的位置用于Maven查找新的插件。

2.7 激活简介

激活简介的范例

<code>settings.xml</code>的最后一个一级元素是<code>activeProfiles</code>。它包含一个<code>activeProfile</code>元素的集合，每个下级元素又包含<code>profile id</code>的值。任何被定义在<code>activeProfile</code>内的<code>profile id</code>都将会被激活，无论其它的环境变量如何配置。如果没有匹配到任何<code>profile</code>，则不会发生任何事情。例如，<code>env-test</code>是一个<code>activeProfile</code>，一个相应的<code>id</code>的在POM内的<code>profile</code>，或者是一个<code>profile.xml</code>就将会被激活。如果没发现这个<code>profile</code>，则执行结果将会和往常一样。

Translation in 8/21 2015 ，By ChangWei Li.