settings.xml详解

介绍

概述

  settings.xml文件中的

<settings />

包含一系列用于配置Maven执行方式的元素，如本地仓库位置、远程仓库服务器和身份验证信息等，类似pom.xml，但不捆绑到任何特定项目，或分发给受众。

  settings.xml文件一般位于以下两个位置：

${maven.home}/conf/settings.xml

${user.home}/.m2/settings.xml

（没有改变settings.xml中本地仓库位置情况下此目录）

  前面位置的settings.xml文件为全局配置文件，后面的为用户配置文件。如果两个配置文件都存在，则以用户配置文件为主合并其内容。

  提示：如果你需要新创建用户配置文件，最简单的方法是将Maven安装目录的全局settings.xml复制到${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/>
<usePluginRegistry/>
<offline/>
<pluginGroups/>
<servers/>
<mirrors/>
<proxies/>
<profiles/>
<activeProfiles/>
</settings>

  可以在settings.xml中使用以下表达式来代替内容:

${user.home}

和所有其他系统属性（自Maven 3.0）

${env.HOME}

等环境变量

  请注意，settings.xml文件中

<profiles>

元素中定义的properties不能用于${expression}。

详细配置

简单值（单值）元素

  一半的顶级配置元素值在构建系统运行期间都是简单值。

<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>
<usePluginRegistry>false</usePluginRegistry>
<offline>false</offline>
...
</settings>

<localRepository />

:配置系统本地仓库的路径。默认值是

${user.home}/.m2/repository

目录。此元素特用于允许所有已登录到主服务器的用户共用公共本地仓库。

<interactiveMode />

：

true

，Maven尝试与用户交互，需用户输入，否则设置为

false

，默认为

true

。

<usePluginRegistry />

：

true

，Maven使用

${user.home}/.m2/plugin-registry.xml

来管理插件版本, 否则

false

。默认值为

false

。Note that for the current version of Maven 2.0, the plugin-registry.xml file should not be depended upon. Consider it dormant for now.(这句话暂时不知如何翻译出来妥当，毕竟已经到Maven 3.x时代)

<offline />

：

true

， 构建系统在离线模式运行，否则

false

。默认值为

false

。此元素对于因网络设置或安全原因而无法连接到远程仓库的服务器非常有用。

<pluginGroups />

  此元素包含一组

<pluginGroup />

元素，每个

<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.mortbay.jetty</pluginGroup>
</pluginGroups>
...
</settings>

  例如，给定上述设置，在Maven命令行能够使用短命令

mvn jetty:run

执行

org.mortbay.jetty:jetty-maven-plugin:run

命令。

<servers />

  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。

username, password：服务器进行身份验证所需的登录名和密码。

privateKey, passphrase:：（可选）与前两个元素类似，这两项指定私钥的路径（默认

${user.home}/.ssh/id_dsa

）和

passphrase

。

passphrase

和

password

元素将来可能外化，但目前它们必须以纯文本形式配置在settings.xml文件中 。

filePermissions, directoryPermissions:：仓库部署时创建的文件或目录的访问权限。这两个元素的合法值是一个三位数字，对应了unix文件系统的权限，如664，或775。

请注意：如果使用私钥登录服务器，请确保没有配置

<password />

元素值，否则，密钥将被忽略。

<mirrors />

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 。构建系统将使用此URL连接到仓库，而不是原始仓库URL。

mirrorOf:：此镜像所镜像的仓库id。例如,指向Maven中央仓库

central repository(https://repo.maven.apache.org/maven2/)

的一个镜像，将此元素设置为

central

。更高级的映射，如

repo1,repo2

or

*,!

也是可以的.，但不能与

<mirror />

的id相同。

  想更深入的了解镜像，请阅读Guide to Mirror Settings。

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

id：此代理的唯一标识符，用于区分

<proxy />

元素。

active：

true

，此代理激活。 当我们声明了一组代理，而某个时刻只需要某一代理激活时用到。

protocol, host, port： 此代理的

protocol://host:port

。

username, password： 代理服务器进行身份验证所需的登录名和密码。

nonProxyHosts：设置不应该被代理的主机列表，列表的分隔符是代理服务器的预期类型，上面的例子是管道分隔符，常见的还有逗号分隔符。

<profiles />

  settings.xml中的

<profile>

元素是pom.xml中

<profile>

元素的截断版本。由

<activation />

、

<propertie
ce24
s />

、

<repositories />

、

<pluginRepositories />

元素组成。

<profile>

元素只包含这四个元素，因为它们作为整个构建系统的一部分，而不是单个项目对象模型的配置。

  如果profile在settings.xml处于活动状态，则其值将覆盖在POM或profiles.xml文件中任id相等的profile配置。

<activation />

  

<activation />

是profile的关键，像POM的profiles一样，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>

  profile在满足所有指定的条件时激活。尽管这些条件不一定一下子都能满足。

jdk：

<jdk />

元素中有一个内置的以Java为中心的检查，当检测到匹配的jdk运行环境，profile被激活，上面的例子中，将匹配 JDK1.5.0_06。

os：

<os />

元素可以定义如上所示的一些操作系统特定属性。

property：如果Maven检测到POM中定义name属性，且值为此

<value />

元素值，则此profile 将被激活。

file:：当给存在并且丢失指定文件名文件，则此profile 将被激活。

  

<activation />

元素并不是激活profile的唯一方式，settings.xml文件中<activeProfile />元素可以指定将被激活的profile id，profile也可以通过在命令行，使用-P标记后跟逗号分隔的列表来显式激活（如，-P test）。

  想要查看哪个profile处于激活状态，使用

maven-help-plugin

。

mvn help:active-profiles

<properties />

  Maven中的

<properties />

是值占位符，类似于Ant中的

<property />

，通过

${X}

在POM文件中的任何地方可以访问它们的值（X为属性）。

  它们有五种不同的形式，都可以在settings.xml文件中使用：

env.X：使用“env.”前缀变量将返回shell环境变量，例如，

${env.PATH}

包含

\$path

环境变量（Windows中为

%PATH%

）.

project.x：点（.）指示POM中对应值的路径。例如通过

${project.version}

访问

<project><version>1.0</version></project>

值。

settings.x：点（.）指示settings.xml中对应值的路径。例如通过

${settings.offline}

访问

<settings><offline>false</offline></settings>

值。

Java System Properties：所有通过

java.lang.System.getProperties()

获得的属性均可用作POM属性。例如

${java.home}

。

x：设置在

<properties />

元素或外部文件中的属性，通过

${someVar}

使用。

  如下，如果此profile处于激活状态，可从POM中访问

${user.install}

属性值。

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

<repositories />

  远程仓库是远程项目集合，Maven使用这些项目来装填构建系统的本地仓库，Maven称之为插件和依赖。不同的远程仓库可能包含不同的项目，处于激活状态下的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>
...
</pluginRepositories>
...
</profile>
</profiles>
...
</settings>

releases, snapshots：设置releases或snapshots版本的artifact的下载策略。使用

<releases/>

和

<snapshots />

，POM能够在单个仓库中独立于其他类型更改每个类型的artifact的下载策略。例如，可能用于开发决定，仅启用快照下载。

enabled：

true

或

false

，表示是否为相应类型启用此仓库。

updatePolicy：此元素指定更新发生的频率，Maven将本地POM的时间戳（存储与仓库的maven元数据文件中）与远程进行比较，可选的设置值有

always

、

daily

（默认）、

interval:X

（X是一分钟为单位的整数）和

never

。

checksumPolicy：当Maven将文件部署到仓库时，它还会验证相应的校验文件，

<checksumPolicy />

配置校验缺失或者不正确时的处理方式，有

ignore

、

fail

、

warn

三个选项值。

layout：在上述对仓库的描述中，提到它们都遵循共同的布局，使用此元素来指定是

default

还是

legacy

。

<pluginRepositories />

  仓库存储两种主要类型的构件，一种是用作其他构件依赖项的组件，中央仓库的大多数构件属于这种类型。 另一种构件类型是插件， Maven插件是一种特殊类型的构件，因此插件仓库可能独立于其他仓库。

<pluginRepositories />

元素的结构类似于

<repositories />

元素， 每个

<pluginRepository />

元素指定了Maven可以查找到新插件的远程地址。

<activeProfiles />

<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将处于激活状态，不管环境设置如何。 如果没有找到匹配的profile，将不产生任何效果。例如，

<activeProfile />

设置profile id为

env-test

，则pom.xml或profile.xml文件中设置id为

env-test

的profile将激活，如果没有匹配的profile，则继续正常执行。

原网址链接Settings Reference