Maven2的配置文件settings.xml

簡介：

概覽

當Maven運行過程中的各種配置，例如pom.xml，不想綁定到一個固定的project或者要分配給用戶時，我們使用settings.xml中的settings元素來確定這些配置。這包含了本地倉庫位置，遠程倉庫服務器以及認證信息等。

settings.xml存在於兩個地方：

1.安裝的地方：$M2_HOME/conf/settings.xml

2.用戶的目錄：${user.home}/.m2/settings.xml

前者又被叫做全局配置，後者被稱爲用戶配置。如果兩者都存在，它們的內容將被合併，並且用戶範圍的settings.xml優先。

如果你偶爾需要創建用戶範圍的settings，你可以簡單的copy Maven安裝路徑下的settings到目錄${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
            http://maven.apache.org/xsd/settings-1.0.0.xsd">
    <localRepository/>
    <interactiveMode/>
    <usePluginRegistry/>
    <offline/>
    <pluginGroups/>
    <servers/>
    <mirrors/>
    <proxies/>
    <profiles/>
    <activeProfiles/>
</settings>

settings的內容可以在下面這些地方篡改：

1.${user.home}和所有其他的系統屬性

2.${env.HOME}等環境變量

注意：settins.xml中profiles下定義的屬性不能被篡改。

配置細節：

簡單的值

一半以上的頂級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.如果一個系統想讓所有登陸的用戶都用同一個本地倉庫的話，這個值是極其有用的。

interactiveMode：如果Maven要試圖與用戶交互來得到輸入就設置爲true，否則就設置爲false，默認爲true。

usePluginRegistry：如果Maven使用${user.home}/.m2/plugin-registry.xml來管理plugin的版本，就設置爲true，默認爲false。

offline：如果構建系統要在離線模式下工作，設置爲true，默認爲false。如果構建服務器因爲網絡故障或者安全問題不能與遠程倉庫相連，那麼這個設置是非常有用的。

插件組

這個元素包含了一系列pluginGroup元素，每個又包含了一個groupId。當一個plugin被使用，而它的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.morbay.jetty:jetty-maven-plugin:run，如下

mvn jetty run

服務器

用來下載和部署的倉庫是用POM中的repositories和distributionManagement元素來定義的。但是某些配置例如username和password就不應該隨着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
            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</filePermissions>
    <directoryPermissions>775</directoryPermissions>
    <configuration></configuration>
    </server>
    </servers>
    ...
</settings>

id：這是Server的ID(不是登錄進來的user)，與Maven想要連接上的repository/mirror中的id元素相匹配。

username，password：這兩個元素成對出現，表示連接這個server需要驗證username和password。

privateKey，passphrase：與前兩個元素一樣，這兩個成對出現，分別指向了一個私鑰(默認的是${user.home}/.ssh/id_dsa)和一個passphrase。passphrase和password元素可能在將來被客觀化，但是現在必須以文本形式在settings.xml中設置。

filePermissions，directoryPermissions：當一個倉庫文件或者目錄在部署階段被創建的時候，就必須用到權限許可。他們合法的值是三個數字，就像*nix中的文件權限，例如：664，775.

注意：如果你使用了一個私鑰來登錄server，那麼password元素必須被省略，否則私鑰將被忽視。

密碼加密

一個新特徵：服務器password和passphrase加密已經被升到2.1.0+

鏡像

<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">
    ...
    <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元素，並且當連接時候被用來獲得相應的證書。

url：鏡像基本的URL，構建系統敬將使用這個URL來連接倉庫，而不是原來的倉庫URL。

mirrorOf：鏡像所包含的倉庫的Id。例如，指向Maven central倉庫的鏡像(http://repo1.maven.org/maven2/)，設置這個元素爲central。更多的高級映射例如repo1,repo2 或者*,!inhouse都是可以的。沒必要一定和mirror的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
            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的唯一標識，用來區別proxy元素。

active：當proxy被激活的時候爲true。當申明的代理很多的時候，這個很有用，但是同一時間僅有一個被激活。

protocol，host，port：代理地址protocol://host:port的分散形式。

username，password：兩個元素成對出現，提供連接proxy服務器時的認證。

nonProxyHosts：這裏列出了不需要使用代理的hosts。列表的分隔符是proxy服務器想要的類型。上面例子使用了pipe分隔符，逗號分隔符也比較通用。

配置文件

settings.xml中的profile是pom.xml中的profile的簡潔形式。它包含了激活(activation)，倉庫(repositories)，插件倉庫(pluginRepositories)和屬性(properties)元素。profile元素僅包含這四個元素是因爲他們涉及到整個的構建系統，而不是個別的POM配置。

如果settings中的profile被激活，那麼它的值將重載POM或者profiles.xml中的任何相等ID的profiles。

激活(activation)

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

如果所有指定的條件都達到了，那麼，activation就被觸發，而且不需要一次性全部達到。

jdk：在jdk元素中，activation有一個內建的，java版本檢測。如果檢測到jdk版本與期待的一樣，那麼就激活。在上面的例子中，1.5.0_06是滿足的。

os：os元素可以定義一些上面所示的操作系統特定的屬性。

property：如果Maven檢測到相應的名值對的屬性，那麼，這個profile將被激活。

file：如果給定的文件存在，或者不存在那麼將激活這個profile。

activation並不是唯一激活profile的途徑。settings.xml中的activeProfile包含了profile的id。他們也可以通過命令行來顯式的激活，例如-P test。

如果你想查看在一個構建過程中有哪些profile會被激活。就使用maven-help-plugin

mvn help:active-profiles

屬性(properites)

Maven的屬性是值佔位符，就像Ant中的屬性。如果X是一個屬性的話，那麼它的值在POM中可以使用${X}來進行任意地方的訪問。他們來自於五種不同的風格，所有都可以從settings.xml文件中訪問到。

1.env.X：使用“env.”前綴將會返回當前的環境變量。例如${env.PATH}就是使用了$path環境變量。

2.project.X：一個點“.”分割的路徑，在POM中就是相關的元素的值。例如：<project><version>1.0</version></project>就可以通過${project.version}來訪問。

3.settings.X：一個點“.”分割的路徑，在settings.xml中就是相對應的元素的值，例如：<settings><offline>false</offline></settings>就可以通過${settings.offline}來訪問。

4.Java系統屬性：所有通過java.lang.System.getProperties()來訪問的屬性都可以像POM中的屬性一樣訪問，例如：${java.home}

5.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
            http://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被激活，那麼屬性${user.install}就可以被訪問了。

倉庫(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
            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>
        <pluginRepositories>
        ...
        </pluginRepositories>
        ...
        </profile>
    </profiles>
    ...
</settings>

releases，snapshots：這是各種構件的策略，release或者snapshot。因了這兩個集合，POM可以在單個的倉庫中不依賴於另外一個的策略而改變當前策略。例如：一個人可能只下載snapshot用來開發。

enable：true或者false，來標記倉庫是否爲各自的類型激活(release 或者 snapshot)。

updatePolicy：這個元素指明瞭更新的頻率。Maven會比較本地POM與遠程的時間戳。可選的項目爲：always，daily，interval:X，nerver。

checksumPolicy：當Maven向倉庫部署文件的時候，它也部署了相應的校驗和文件。可選的爲：ignore，fail，warn，或者不正確的校驗和。

layout：在上面描述倉庫的時候，我們提到他們有統一的佈局。這完全正確。使用這個來表明它是default還是legacy。

插件倉庫(plugin repositories)

倉庫包含了兩種重要類型的構件。第一種是用來做其他構件依賴的構件，這是在中央倉庫中的大多數插件。另外一種類型的構件就是插件。Maven的插件本身就是一種特殊的構件。因此，插件倉庫被從其他倉庫中分離出來。無論怎麼說，pluginRepositories元素模塊的結構與repositories模塊很相似。pluginRepository元素指向一個可以找到新插件的遠程地址。

激活配置(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最後一個謎題是activeProfiles元素。它包含一系列的activeProfile元素，每個都有一個profile id的值，任何profile id被定義到activeProfile的profile將被激活，不管其他的環境設置怎麼樣。如果沒有匹配的profile被找到，那麼就什麼事情也不做。例如：如果env-test是一個activeProfile，一個在pom.xml或者profile.xml中的具有相應id的profile將被激活。如果沒有這樣的profile被找到，就什麼事也不做，一切照常。

原文地址：http://maven.apache.org/settings.html