Settings 参考

Introduction

简单概述

settings.xml文件中settings元素包含用于配置Maven不同执行方式定义值的元素，就像pom.xml，但是settings.xml中配置不应该与某一项目绑定。settings.xml中包含诸如本地仓库位置或者远程仓库服务配置再或者认证信息等值。

settings.xml可能存在的两个地方：

maven安装目录下：${maven.home}/conf/settings.xml
用户安装目录下：${user.home}/.m2/settings.xml

前者也叫全局配置，后者则被称为用户配置。如果两个文件都存在，那么将合并两者的内容，并且以用户指定的settings.xml为主。

小决窍：如果你碰巧需要创建用户配置，最简单的方式就是将Maven安装目录下的全局配置直接拷贝到你的${user.home}/.m2目录下。Maven的默认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
                        http://maven.apache.org/xsd/settings-1.0.0.xsd">
    <localRepository/>
    <interactiveMode/>
    <usePluginRegistry/>
    <offline/>
    <pluginGroups/>
    <servers/>
    <mirrors/>
    <proxies/>
    <profiles/>
    <activeProfiles/>
</settings>

settings.xml的内容可以通过如下表达式插值：

1.user.home和其他所有的系统属性（从3.0开始）2. {env.HOME}等用于取环境变量的值

注：settings.xml中profiles下属性定义不能使用上面插值方式。

Settings 细节

简单配置值

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
                            http://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。
usePluginRegistry:如果想要maven使用${user.home}/.m2/plugin-registry.xml文件来管理插件版本，可设置为true，默认为false。
interactiveMode:如果想要Maven与用户输入交互，设置为true，反之false，默认为true。
offline:如果构建系统需要以线下模式操作，设置为true，默认为false。此元素常用于构建或者因为网络安装或者因为安全原因不能连接到远程仓库的服务。

Plugin Groups

此元素包含一个pluginGroup元素列表。当要使用一个插件但是没有在命令行中提供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
                        http://maven.apache.org/xsd/settings-1.0.0.xsd">
    ...
    <pluginGroups>
        <pluginGroup>org.mortbay.jetty</pluginGroup>
    </pluginGroups>
    ...
</settings>

例如，如果使用如上配置，在Maven命令行中执行如下命令时，将执行org.mortbay.jetty:jetty-maven-plugin:run

mvn jetty:run

Servers

用于下载和发布的仓库分别由pom.xml的repositories元素和distributionManagement元素定义，但是某些比如用户名和密码信息则不应该在pom.xml中出现，应该配置在settings.xml中的server元素中：

<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
                        http://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</filePermisions>
            <directoryPermissions>775</directoryPermissions>
            <configuration></configuration>
        </server>
    </servers>
    ...
</settings>

id:配置服务的ID，与Maven试图连接的repository或者mirror元素的ID。
username, password:两者成对出现，用于指定认证到此服务的用户名与密码。
privateKey, passphrase:同上面两个类似，这一对用于指定私钥文件所在路径与暗语。
filePermissions, directoryPermissions:指定当一个仓库文件或者目录基于发布创建时的访问权限。

注：如果使用私钥登录到服务器，那么就缺省掉password元素，否则私钥将被忽略。

Mirrors

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
    xmlns:xsi="http://www.w3.org/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
                        http://maven.apache.org/xsd/settings-1.0.0.xsd">
    ...
    <mirrors>
        <mirror>
            <id>planetmirror.com</id>
            <name>PlanetMirror</name>
            <url>http://downloads.planetmirror.com</url>
            <mirrorOf>central</mirrorOf>
        </mirror>
    </mirrors>
    ...
</settings>

id,name:惟一标识和此镜像的友好名称。通过ID的不同来从

Proxies

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
    xmlns:xsi="http://www.w3.org/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
                        http://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:指定不被代理的列表，可使用管道（|）或者逗号（,）作为分隔符。

Profiles

settings.xml中的profile元素是pom.xml中profile元素的删减版。它由activation,repositories,pluginRepositories四个元素组成，因为此四项与不与单个项目构建相关。

如果在settings.xml中配置一个profile的激活，那么它将覆盖pom.xml中或者profiles.xml中任何与它ID相同的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
                        http://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版本时激活。
os:当前操作系统满足OS指定属性时激活。
property:当Maven检测到对应的name=value键值对属性（一个可以在pom.xml中通过${name}间接引用的值）时激活。
file:最后，如果存在或者丢失指定名称文件时激活。

activation 元素并不是激活profile的惟一方式，也可以通过settings.xml中activeProfile元素指定要激活profile元素ID的方式或者命令行中-P选项后加要激活profile元素ID的方式激活。

Properties

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

env.X:用于获取环境变量的值。例如：${env.PATH}表示访问系统环境变量PATH的值。
project.X:用于访问pom.xml中对应元素的值，如

Repositories

Repositories 元素用于指定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
                        http://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>
            ...
        </profile>
    </profiles>
    ...
</settings>

releases, snapshots:指定要下载的是发布版还是快照版。
enabled：是否启用releases或者snapshots。
updatePolicy：用于指定更新频率，可用的值有always,daily,interval:X(X是一个整数，单位为秒),never。
checksumPolicy：当Maven向仓库布署文件时，同时也会发布对应的校验文件，此处为指定丢失或者校验失败时的策略，可选值为ignore,fail,warn。
layout：指定仓库布局，可选值有default,legacy。

Plugin Repositories

同Repositories元素类似，但是用于指定插件仓库。

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
                        http://maven.apache.org/xsd/settings-1.0.0.xsd">
    ...
    <activeProfiles>
        <activeProfile>env-test</activeProfile>
    </activeProfiles>
</settings>

此元素为settings.xml文件中的最后部分，可包含一个activeProfile元素集。每个activeProfile元素的值与profile元素的ID相对应。无论任何的环境配置，只要在activeProfile元素中配置的profile都会被激活，如果没有相匹配的profile元素，则什么都不做。

Maven Settings