Maven Settings

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元素，則什麼都不做。