The settings.xml File in Maven – Maven中的settings.xml文件

最后修改: 2021年 6月 24日

中文/混合/英文(键盘快捷键：t)

1. Overview

1.概述

While using Maven, we keep most of the project-specific configuration in the pom.xml.

在使用Maven时，我们将大部分项目的特定配置放在pom.xml中。

Maven provides a settings file, settings.xml, which allows us to specify which local and remote repositories it will use. We can also use it to store settings that we don’t want in our source code, such as credentials.

Maven提供了一个设置文件，settings.xml，它允许我们指定它将使用哪些本地和远程存储库。我们还可以用它来存储我们不希望在源代码中出现的设置，比如说证书。

In this tutorial, we’ll learn how to use the settings.xml. We’ll look at proxies, mirroring, and profiles. We’ll also discuss how to determine the current settings that apply to our project.

在本教程中，我们将学习如何使用settings.xml。我们将研究代理、镜像和配置文件。我们还将讨论如何确定适用于我们项目的当前设置。

2. Configurations

2.配置

The settings.xml file configures a Maven installation. It’s similar to a pom.xml file but is defined globally or per user.

settings.xml文件用于配置Maven安装。它类似于pom.xml文件，但可以全局或按用户定义。

Let’s explore the elements we can configure in the settings.xml file. The main settings element of the settings.xml file can contain nine possible predefined child elements:

让我们探讨一下我们可以在settings.xml文件中配置的元素。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>

2.1. Simple Values

2.1.简单的价值观

Some of the top-level configuration elements contain simple values:

一些顶层的配置元素包含简单的值。

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

The localRepository element points to the path of the system’s local repository. The local repository is where all the dependencies from our projects get cached. The default is to use the user’s home directory. However, we could change it to allow all logged-in users to build from a common local repository.

localRepository元素指向系统的本地资源库路径。local repository是我们项目中所有依赖项的缓存地点。默认情况是使用用户的主目录。不过，我们可以改变它，让所有登录的用户都从一个共同的本地仓库构建。

The interactiveMode flag defines if we allow Maven to interact with the user asking for input. This flag defaults to true.

interactiveMode标志定义了我们是否允许Maven与用户互动，要求输入。该标志的默认值为true。

The offline flag determines if the build system may operate in offline mode. This defaults to false; however, we can switch it to true in cases where the build servers cannot connect to a remote repository.

offline标志决定了构建系统是否可以在离线模式下运行。默认为false；然而，在构建服务器无法连接到远程仓库的情况下，我们可以将其切换为true。

2.2. Plugin Groups

2.2.插件组

The pluginGroups element contains a list of child elements that specify a groupId. A groupId is the unique identifier of the organization that created a specific Maven artifact:

pluginGroups元素包含一个指定groupId的子元素列表。groupId是创建特定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">
    <pluginGroups>
        <pluginGroup>org.apache.tomcat.maven</pluginGroup>
    </pluginGroups>
</settings>

Maven searches the list of plugin groups when a plugin is used without a groupId provided at the command line. The list contains the groups org.apache.maven.plugins and org.codehaus.mojo by default.

当使用一个没有提供groupId的插件时，Maven会搜索插件组列表 在命令行。该列表默认包含org.apache.maven.plugins和org.codehaus.mojo组。

The settings.xml file defined above allows us to execute truncated Tomcat plugin commands:

上面定义的settings.xml文件允许我们执行截短的Tomcat插件命令。

mvn tomcat7:help
mvn tomcat7:deploy
mvn tomcat7:run

2.3. Proxies

2.3.代理人

We can configure a proxy for some or all of Maven’s HTTP requests. The proxies element allows a list of child proxy elements, but only one proxy can be active at a time:

我们可以为部分或全部Maven的HTTP请求配置一个代理。代理元素允许一个子代理元素的列表，但一次只能有一个代理在活动。

<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>baeldung-proxy</id>
            <active>true</active>
            <protocol>http</protocol>
            <host>baeldung.proxy.com</host>
            <port>8080</port>
            <username>demo-user</username>
            <password>dummy-password</password>
            <nonProxyHosts>*.baeldung.com|*.apache.org</nonProxyHosts>
        </proxy>
    </proxies>
</settings>

We define the currently active proxy via the active flag. Then with the nonProxyHosts element, we specify which hosts are not proxied. The delimiter used depends on the specific proxy server. The most common delimiters are pipe and comma.

我们通过active标志定义当前活动的代理。然后通过nonProxyHosts元素，我们指定哪些主机不被代理。使用的定界符取决于具体的代理服务器。最常见的定界符是管道和逗号。

2.4. Mirrors

2.4.镜子

Repositories can be declared inside a project pom.xml. This means that the developers sharing the project code get the right repository settings out of the box.

仓库可以在项目 pom.xml.内声明，这意味着共享项目代码的开发者可以开箱即得正确的仓库设置。

We can use mirrors in cases where we want to define an alternative mirror for a particular repository. This overrides what’s in the pom.xml.

在我们想要定义某个特定版本库的替代镜像的情况下，我们可以使用镜像。这将覆盖pom.xml中的内容。

For example, we can force Maven to use a single repository by mirroring all repository requests:

例如，我们可以通过镜像所有版本库的请求，强制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">
    <mirrors>
        <mirror>
            <id>internal-baeldung-repository</id>
            <name>Baeldung Internal Repo</name>
            <url>https://baeldung.com/repo/maven2/</url>
            <mirrorOf>*</mirrorOf>
        </mirror>
    </mirrors>
</settings>

We may define only one mirror for a given repository and Maven will pick the first match. Normally, we should use the official repository distributed worldwide via CDN.

我们可以为一个给定的版本库只定义一个镜像，Maven会选择第一个匹配的。通常情况下，我们应该使用通过CDN分发到世界各地的官方仓库。

2.5. Servers

2.5.服务器

Defining repositories in the project pom.xml is a good practice. However, we shouldn’t put security settings, such as credentials, into our source code repository with the pom.xml. Instead, we define this secure information in the settings.xml file:

在项目pom.xml中定义资源库是一个好的做法。然而，我们不应该把安全设置，如凭证，放在我们的源代码库中与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>internal-baeldung-repository</id>
            <username>demo-user</username>
            <password>dummy-password</password>
            <privateKey>${user.home}/.ssh/bael_key</privateKey>
            <passphrase>dummy-passphrase</passphrase>
            <filePermissions>664</filePermissions>
            <directoryPermissions>775</directoryPermissions>
            <configuration></configuration>
        </server>
    </servers>
</settings>

We should note that the ID of the server in the settings.xml needs to match the ID element of the repository mentioned in the pom.xml. The XML also allows us to use placeholders to pick up credentials from environment variables.

我们应该注意，settings.xml中服务器的ID需要与pom.xml中提到的版本库的ID元素匹配。XML还允许我们使用占位符来从环境变量中获取凭证。

3. Profiles

3.概况

The profiles element enables us to create multiple profile child elements differentiated by their ID child element. The profile element in the settings.xml is a truncated version of the same element available in the pom.xml.

profiles元素使我们能够创建多个profile子元素，通过其ID子元素加以区分。settings.xml中的profile元素是pom.xml中相同元素的一个截断版本。

It can contain only four child elements: activation, repositories, pluginRepositories, and properties. These elements configure the build system as a whole, instead of any particular project.

它只能包含四个子元素。激活、存储库、插件存储库和属性。这些元素将构建系统作为一个整体进行配置，而不是任何特定的项目。

It’s important to note that values from an active profile in settings.xml will override any equivalent profile values in a pom.xml or profiles.xml file. Profiles are matched by ID.

值得注意的是，settings.xml中的活动配置文件的值将覆盖pom.xml或profiles.xml文件中的任何相等的配置文件值。配置文件是通过ID来匹配的。

3.1. Activation

3.1.激活

We can use profiles to modify certain values only under given circumstances. We can specify those circumstances using the activation element. Consequently, profile activation occurs when all specified criteria are met:

我们可以使用配置文件，只在给定的情况下修改某些值。我们可以使用激活元素来指定这些情况。因此，当所有指定的标准得到满足时，配置文件会被激活。

<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>baeldung-test</id>
            <activation>
                <activeByDefault>false</activeByDefault>
                <jdk>1.8</jdk>
                <os>
                    <name>Windows 10</name>
                    <family>Windows</family>
                    <arch>amd64</arch>
                    <version>10.0</version>
                </os>
                <property>
                    <name>mavenVersion</name>
                    <value>3.0.7</value>
                </property>
                <file>
                    <exists>${basedir}/activation-file.properties</exists>
                    <missing>${basedir}/deactivation-file.properties</missing>
                </file>
            </activation>
        </profile>
    </profiles>
</settings>

There are four possible activators and not all of them need to be specified:

有四种可能的激活器，并不是所有的激活器都需要被指定。

  • jdk: activates based on the JDK version specified (ranges are supported)
  • os: activates based on operating system properties
  • property: activates the profile if Maven detects a specific property value
  • file: activates the profile if a given filename exists or is missing

In order to check which profile will activate a certain build, we can use the Maven help plugin:

为了检查哪个配置文件能激活某个构建，我们可以使用Maven帮助插件。

mvn help:active-profiles

The output will display currently active profiles for a given project:

输出将显示一个给定项目的当前激活的配置文件。

[INFO] --- maven-help-plugin:3.2.0:active-profiles (default-cli) @ core-java-streams-3 ---
[INFO]
Active Profiles for Project 'com.baeldung.core-java-modules:core-java-streams-3:jar:0.1.0-SNAPSHOT':
The following profiles are active:
 - baeldung-test (source: com.baeldung.core-java-modules:core-java-streams-3:0.1.0-SNAPSHOT)

3.2. Properties

3.2.属性

Maven properties can be thought of as named placeholders for a certain value. The values are accessible within a pom.xml file using the ${property_name} notation:

Maven属性可以被认为是某一数值的命名占位符。这些值可以在pom.xml文件中使用${property_name}符号访问。

<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>baeldung-test</id>
            <properties>
                <user.project.folder>${user.home}/baeldung-tutorials</user.project.folder>
            </properties>
        </profile>
    </profiles>
</settings>

Four different types of properties are available in pom.xml files:

在pom.xml文件中，有四种不同类型的属性。

  • Properties using the env prefix return an environment variable value, such as ${env.PATH}.
  • Properties using the project prefix return a property value set in the project element of the pom.xml, such as ${project.version}.
  • Properties using the settings prefix return the corresponding element’s value from the settings.xml, such as ${settings.localRepository}.
  • We may reference all properties available via the System.getProperties method in Java directly, such as ${java.home}.
  • We may use properties set within a properties element without a prefix, such as ${junit.version}.

3.3. Repositories

3.3.存储库

Remote repositories contain collections of artifacts that Maven uses to populate our local repository. Different remote repositories may be needed for particular artifacts. Maven searches the repositories enabled under the active profile:

远程仓库包含工件的集合，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>
            <id>adobe-public</id>
            <repositories>
	        <repository>
	            <id>adobe-public-releases</id>
	            <name>Adobe Public Repository</name>
	            <url>https://repo.adobe.com/nexus/content/groups/public</url>
	            <releases>
	                <enabled>true</enabled>
	                <updatePolicy>never</updatePolicy>
	            </releases>
	            <snapshots>
	                <enabled>false</enabled>
	            </snapshots>
	        </repository>
	    </repositories>
        </profile>
    </profiles>
</settings>

We can use the repository element to enable only release or snapshots versions of artifacts from a specific repository.

我们可以使用repository元素，只启用特定存储库的工件的发布或快照版本。

3.4. Plugin Repositories

3.4.插件库

There are two standard types of Maven artifacts, dependencies and plugins. As Maven plugins are a special type of artifact, we may separate plugin repositories from the others:

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>
            <id>adobe-public</id>
            <pluginRepositories>
               <pluginRepository>
                  <id>adobe-public-releases</id>
                  <name>Adobe Public Repository</name>
                  <url>https://repo.adobe.com/nexus/content/groups/public</url>
                  <releases>
                      <enabled>true</enabled>
                      <updatePolicy>never</updatePolicy>
                  </releases>
                  <snapshots>
                      <enabled>false</enabled>
                  </snapshots>
	        </pluginRepository>
	    </pluginRepositories>
        </profile>
    </profiles>
</settings>

Notably, the structure of the pluginRepositories element is very similar to the repositories element.

值得注意的是，pluginRepositories元素的结构与repositories元素非常相似。

3.5. Active Profiles

3.5.活跃概况

The activeProfiles element contains child elements that refer to a specific profile ID. Maven automatically activates any profile referenced here:

activeProfiles元素包含指向特定配置文件ID的子元素。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">
    <activeProfiles>
        <activeProfile>baeldung-test</activeProfile>
        <activeProfile>adobe-public</activeProfile>
    </activeProfiles>
</settings>

In this example, every invocation of mvn is run as though we’ve added -P baeldung-test,adobe-public to the command line.

在这个例子中，每一次调用mvn都是像我们在命令行中加入-P baeldung-test,adobe-public那样运行。

4. Settings Level

4.设置级别

A settings.xml file is usually found in a couple of places:

一个settings.xml文件通常可以在几个地方找到。

  • Global settings in Mavens home directory: ${maven.home}/conf/settings.xml
  • User settings in the user’s home: ${user.home}/.m2/settings.xml

If both files exist, their contents are merged. Configurations from the user settings take precedence.

如果两个文件都存在，它们的内容会被合并。用户设置中的配置具有优先权。

4.1. Determine File Location

4.1.确定文件位置

In order to determine the location of global and user settings, we can run Maven using the debug flag and search for “settings” in the output:

为了确定全局和用户设置的位置，我们可以使用调试标志运行Maven，在输出中搜索“settings”。

$ mvn -X clean | grep "settings"

[DEBUG] Reading global settings from C:\Program Files (x86)\Apache\apache-maven-3.6.3\bin\..\conf\settings.xml
[DEBUG] Reading user settings from C:\Users\Baeldung\.m2\settings.xml

4.2. Determine Effective Settings

4.2.确定有效设置

We can use the Maven help plugin to find out the contents of the combined global and user settings:

我们可以使用Maven帮助插件，找出全局和用户设置的组合内容。

mvn help:effective-settings

This describes the settings in XML format:

这是以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">
    <localRepository>C:\Users\Baeldung\.m2\repository</localRepository>
    <pluginGroups>
        <pluginGroup>org.apache.tomcat.maven</pluginGroup>
        <pluginGroup>org.apache.maven.plugins</pluginGroup>
        <pluginGroup>org.codehaus.mojo</pluginGroup>
    </pluginGroups>
</settings>

4.3. Override the Default Location

4.3.覆盖默认位置

Maven also allows us to override the location of the global and user settings via the command line:

Maven还允许我们通过命令行覆盖全局和用户设置的位置。

$ mvn clean --settings c:\user\user-settings.xml --global-settings c:\user\global-settings.xml

We can also use the shorter –s version of the same command:

我们也可以使用同一命令的较短-s版本。

$ mvn clean --s c:\user\user-settings.xml --gs c:\user\global-settings.xml

5. Conclusion

5.总结

In this article, we explored the configurations available in Maven’s settings.xml file.

在这篇文章中，我们探讨了Maven的settings.xml文件中的可用配置。

We learned how to configure proxies, repositories and profiles. Next, we looked at the difference between global and user settings files, and how to determine which are in use.

我们学习了如何配置代理、存储库和配置文件。接下来，我们研究了全局和用户设置文件之间的区别，以及如何确定哪些文件正在使用。

Finally, we looked at determining the effective settings used, and overriding default file locations.

最后，我们研究了确定使用的有效设置，以及覆盖默认文件位置。