以下内容为官网内容翻译。原文入口
介绍
简要介绍
settings.xml
文件中的 settings
元素包含用于定义配置 Maven 执行方式的值的元素,类似于 pom.xml
,但不应捆绑到任何特定项目,也不应分发给任何用户。其中包括本地仓库位置、备用远程仓库服务器和身份验证信息等值。
settings.xml
文件可以存在于两个位置:
- Maven 安装目录:
${maven.home}/conf/settings.xml
- 用户安装目录:
${user.home}/.m2/settings.xml
前者的 settings.xml
也被称为全局设置,而后者的 settings.xml
被称为用户设置。如果两个文件都存在,它们的内容会被合并,以用户特定的 settings.xml
为主。
提示:如果你需要从头开始创建用户特定的设置,最简单的方法是将 Maven 安装中的全局设置复制到 ${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/>
<offline/>
<pluginGroups/>
<servers/>
<mirrors/>
<proxies/>
<profiles/>
<activeProfiles/>
</settings>
settings.xml
文件的内容可以使用以下表达式进行插值:
${user.home}
和所有其他系统属性(自 Maven 3.0 起)${env.HOME}
等用于环境变量
请注意,在 settings.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 https://maven.apache.org/xsd/settings-1.0.0.xsd">
<localRepository>${user.home}/.m2/repository</localRepository>
<interactiveMode>true</interactiveMode>
<offline>false</offline>
...
</settings>
- localRepository(本地仓库): 该值是构建系统本地仓库的路径。默认值为
${user.home}/.m2/repository
。对于主构建服务器允许所有登录用户从共同的本地仓库构建的情况,此元素特别有用。 - interactiveMode(交互模式): 如果 Maven 应尝试与用户进行交互以获取输入,则为 true;如果不需要,则为 false。默认为 true。
- offline(离线模式): 如果该构建系统应该在离线模式下运行,则为 true;默认为 false。对于不能连接到远程仓库的构建服务器,可能是由于网络设置或安全原因,此元素很有用。
Plugin Groups
pluginGroups
元素包含一个 pluginGroup
列表,每个 pluginGroup
包含一个 groupId
。当使用插件而在命令行中未提供 groupId
时,Maven 会搜索此列表。此列表自动包含 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.eclipse.jetty</pluginGroup>
</pluginGroups>
...
</settings>
例如,给定上述设置,Maven 命令行可能会执行 org.eclipse.jetty:jetty-maven-plugin:run
,对应的截断命令可能如下:
mvn jetty:run
命令中的jetty为什么不是jetty-maven-plugin,也能找到相应的插件。而且下面这种方式却无法找到插件?
mvn 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: 这是服务器的ID(而不是要登录的用户的ID),与 Maven 尝试连接的 repository/mirror 的 id 元素相匹配。
username、password: 这些元素成对出现,表示身份验证到该服务器所需的登录名和密码。
privateKey、passphrase: 与前两个元素类似,这对元素指定了私钥的路径(默认为 ${user.home}/.ssh/id_dsa)和密语(如果需要)。将来,密语和密码的元素可能会外部化,但目前它们必须以明文形式设置在 settings.xml
文件中。
filePermissions、directoryPermissions: 当在部署时创建存储库文件或目录时,使用的权限是这两个元素。每个元素的合法值是对应于 *nix 文件权限的三位数字,例如 664 或 775。
注意:如果你使用私钥登录到服务器,请确保省略 <password>
元素。否则,该密钥将被忽略。
Password Encryption
新功能——服务器密码和密语加密已添加到 2.1.0+ 版本中。详细信息请参阅 此页面open in new window。
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 用于区分不同的镜像元素,并在连接到镜像时从 <servers>
部分选择相应的凭据。
url: 这是镜像的基本 URL。构建系统将使用此 URL 连接到仓库,而不是使用原始的仓库 URL。
mirrorOf: 这是仓库的 id,这是该镜像的原始仓库。例如,要指向 Maven 中央仓库的镜像(https://repo.maven.apache.org/maven2/),将此元素设置为 central。更高级的映射,如 repo1,repo2 或 *,!inhouse 也是可能的。这不能与镜像的 id 匹配。
Mirrors的更多设置参考open in new window.
使用镜像仓
使用仓库,您可以指定从哪些位置下载特定的构件,例如依赖项和 Maven 插件。仓库可以在项目内声明,这意味着如果您有自己的自定义仓库,那些与您的项目共享的人可以轻松地获得正确的设置。但是,您可能希望在不更改项目文件的情况下为特定仓库使用替代镜像。
使用镜像的一些原因包括:
- 有一个在互联网上同步的镜像,地理位置更近,速度更快
- 您想要用您有更大控制权的内部仓库替换特定的仓库
- 您想要运行一个仓库管理器,为镜像提供本地缓存,并需要使用其 URL
要配置给定仓库的镜像,您需要在设置文件中提供它(${user.home}/.m2/settings.xml
),为新仓库提供其自己的 ID 和 URL,并指定 mirrorOf
设置为您使用的镜像的仓库 ID。例如,默认包含的主 Maven 中央仓库的 ID 是 central
,因此要使用不同的镜像实例,您可以配置如下:
<settings>
...
<mirrors>
<mirror>
<id>other-mirror</id>
<name>Other Mirror Repository</name>
<url>https://other-mirror.repo.other-company.com/maven2</url>
<mirrorOf>central</mirrorOf>
</mirror>
</mirrors>
...
</settings>
请注意,对于给定的仓库最多只能有一个镜像。换句话说,您不能将单个仓库映射到一组镜像,它们都定义相同的 <mirrorOf>
值。Maven 不会汇总镜像,而是简单地选择第一个匹配项。如果您想提供多个仓库的组合视图,请使用仓库管理器。
设置描述符的文档可以在 Maven 本地设置模型网站上找到。
注意:官方的 Maven 仓库位于由 Sonatype 公司托管的 https://repo.maven.apache.org/maven2,并通过 CDN 分布到全球。
已知镜像的列表可在仓库元数据中找到。这些镜像可能不具有相同的内容,我们不以任何方式支持它们。
使用单仓库
<settings>
...
<mirrors>
<mirror>
<id>internal-repository</id>
<name>Maven Repository Manager running on repo.mycompany.com</name>
<url>http://repo.mycompany.com/proxy</url>
<mirrorOf>*</mirrorOf>
</mirror>
</mirrors>
...
</settings>
您可以通过让 Maven 镜像所有仓库请求来强制其使用单一仓库。该仓库必须包含所有所需的构件,或者能够代理请求到其他仓库。当使用内部公司仓库并使用 Maven 仓库管理器代理外部请求时,此设置最有用。
要实现这一点,请将 mirrorOf
设置为 *。
注意:此功能仅在 Maven 2.0.5+ 版本中可用。
高级镜像定义
一个镜像可以处理多个仓库。通常与仓库管理器一起使用,它提供了对位于其后的仓库列表的轻松集中配置。
语法:
-
匹配所有仓库标识。
-
external:* 匹配除了使用 localhost 或基于文件的仓库之外的所有仓库。在想要排除为集成测试定义的重定向仓库时使用。
-
自Maven 3.8.0开始,external:http:* 匹配所有使用HTTP的仓库,除了使用 localhost 的仓库。
-
可以使用逗号作为分隔符指定多个仓库 感叹号可以与上述通配符之一结合使用,以排除仓库标识
注意在逗号分隔的列表中不要包含标识符或通配符周围的额外空格。例如,设置为 !repo1,* 的镜像不会镜像任何内容,而 !repo1,* 将会镜像除了 repo1 之外的所有内容。
通配符在仓库标识符的逗号分隔列表中的位置并不重要,因为通配符推迟到进一步处理,而显式包含或排除会停止处理,覆盖任何通配符匹配。
当使用高级语法并配置多个镜像时,声明顺序很重要。当Maven查找某个仓库的镜像时,首先检查镜像的<mirrorOf>是否与仓库标识符完全匹配。如果没有找到直接匹配,Maven会选择根据上述规则(如果有的话)找到的第一个镜像声明。因此,您可以通过更改settings.xml中定义的顺序来影响匹配顺序。
示例:
- *= 所有内容
- external:* = 不在 localhost 上且不基于文件的所有内容。
- repo,repo1 = repo 或 repo1
- *,!repo1 = 除了 repo1 之外的所有内容
<settings>
...
<mirrors>
<mirror>
<id>internal-repository</id>
<name>Maven Repository Manager running on repo.mycompany.com</name>
<url>http://repo.mycompany.com/proxy</url>
<mirrorOf>external:*,!foo</mirrorOf>
</mirror>
<mirror>
<id>foo-repository</id>
<name>Foo</name>
<url>http://repo.mycompany.com/foo</url>
<mirrorOf>foo</mirrorOf>
</mirror>
</mirrors>
...
</settings>
创建自己的镜像
中央仓库的大小正在稳步增长open in new window。为了节省带宽并节约您的时间,不允许镜像整个中央仓库(这样做将自动导致封禁)。相反,我们建议您设置一个 仓库管理器open in new window 作为代理。
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>
...
</settings>
id: 用于标识此代理的唯一标识符。用于区分代理元素之间的差异。
active: 如果此代理处于活动状态,则为true。这对于声明一组代理很有用,但一次只能有一个代理处于活动状态。
protocol、host、port: 代理的协议://主机:端口,分成单独的元素。
username、password: 这些元素成对出现,表示登录到此代理服务器所需的用户名和密码。
nonProxyHosts: 这是一个不应该被代理的主机列表。列表的分隔符是代理服务器的期望类型;上面的示例使用了管道分隔符,逗号分隔符也很常见。
Profiles
settings.xml中的profile元素是pom.xml中profile元素的截断版本。它由activation、repositories、pluginRepositories和properties元素组成。profile元素只包括这四个元素,因为它们关注整个构建系统(这是settings.xml文件的作用),而不涉及个别项目对象模型设置。
如果从settings激活了一个profile,它的值将覆盖POM或profiles.xml文件中具有相同ID的任何profile。
Activation
激活是profile的关键。与POM的profiles类似,profile的强大之处在于其能力,即只在特定条件下修改某些值;这些条件通过激活元素指定。
<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>
激活发生在满足所有指定条件时,尽管并非所有条件一次都是必需的。
jdk:激活在jdk元素中具有内置的、以Java为中心的检查。如果测试在与给定前缀匹配的jdk版本号下运行,则将激活。在上面的例子中,1.5.0_06将匹配。还支持范围。有关支持的范围的详细信息,请参见 maven-enforcer-pluginopen in new window 。
os:os元素可以定义一些上面显示的特定于操作系统的属性。有关操作系统值的详细信息,请参见 maven-enforcer-pluginopen in new window 。
property:如果Maven检测到相应名称=值对的属性(可以在POM中通过${name}进行解引用),则将激活该配置文件。
file:最后,通过文件的存在或缺失,可以通过给定的文件名激活配置文件。
激活元素并非配置文件被激活的唯一方式。settings.xml文件的activeProfile元素可以包含配置文件的id。它们也可以通过命令行显式激活,使用-P标志后跟逗号分隔的列表(例如,-P test)。
要查看在特定构建中哪个配置文件将被激活,请使用maven-help-plugin。
mvn help:active-profiles
Properties
Maven属性是值占位符,类似于Ant中的属性。它们的值可以在POM的任何地方通过使用符号${X}访问,其中X是属性的名称。它们有五种不同的样式,都可以从settings.xml文件中访问:
- env.X: 在变量前加上“env.”将返回shell的环境变量。例如,${env.PATH}包含$path环境变量(在Windows中为%PATH%)。
- project.x: POM中的点(.)标记路径将包含相应元素的值。例如:<project><version>1.0</version></project>可以通过${project.version}访问。
- settings.x: settings.xml中的点(.)标记路径将包含相应元素的值。例如:<settings><offline>false</offline></settings>可以通过${settings.offline}访问。
- Java系统属性: 通过java.lang.System.getProperties()可访问的所有属性都作为POM属性可用,例如${java.home}。
- 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 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>
如果此配置文件处于活动状态,则可以从POM中访问属性${user.install}。
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 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>
<pluginRepository>
<id>myPluginRepo</id>
<name>My Plugins repo</name>
<releases>
<enabled>true</enabled>
</releases>
<snapshots>
<enabled>false</enabled>
</snapshots>
<url>https://maven-central-eu....com/maven2/</url>
</pluginRepository>
</pluginRepositories>
...
</profile>
</profiles>
...
</settings>
releases、snapshots:这些是每种类型构件(发布或快照)的策略。通过这两组策略,一个POM有能力在单个仓库内独立于另一种类型改变每种类型构件的策略。例如,可以决定仅启用快照下载,可能用于开发目的。
enabled:用于指定此仓库是否对相应类型(发布或快照)启用,值为true或false。
updatePolicy:此元素指定更新应该尝试发生的频率。Maven将比较本地POM的时间戳(存储在仓库的maven-metadata文件中)与远程的时间戳。选择包括:always、daily(默认)、interval:X(其中X是以分钟为单位的整数)或never。
checksumPolicy:当Maven将文件部署到仓库时,还会部署相应的校验文件。选项包括忽略(ignore)、失败(fail)或在缺少或不正确的校验时发出警告(warn)。 layout:在上述仓库的描述中,提到它们都遵循一个常见的布局。这基本上是正确的。Maven 2对其仓库有一个默认布局;但是,Maven 1.x有一个不同的布局。使用此元素指定是否使用默认布局或旧版布局。
Plugin Repositories
仓库是两种主要类型的构件的存储地。第一种是作为其他构件的依赖项使用的构件。这些构件占据了中央仓库的大部分。另一种类型的构件是插件。Maven插件本身就是一种特殊类型的构件。因此,插件仓库可以与其他仓库分开(尽管我尚未听到令人信服的这样做的理由)。在任何情况下,pluginRepositories元素块的结构类似于repositories元素。每个pluginRepository元素都指定Maven可以找到新插件的远程位置。
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 https://maven.apache.org/xsd/settings-1.0.0.xsd">
...
<activeProfiles>
<activeProfile>env-test</activeProfile>
</activeProfiles>
</settings>
settings.xml中的最后一部分是activeProfiles元素。它包含一组activeProfile元素,每个元素都有一个profile id的值。作为activeProfile定义的任何profile id都将处于活动状态,而不考虑任何环境设置。如果没有找到匹配的配置文件,则不会发生任何事情。例如,如果env-test是一个activeProfile,那么在pom.xml中的配置文件(或具有相应id的profile.xml)将是活动的。如果没有找到这样的配置文件,则执行将继续正常进行。