The settings.xml File in Maven

最后修改: 2022-05-21T04:43:32+00:00

1. 概述

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

Maven 提供了一个设置文件 settings.xml， 它允许我们指定它将使用哪些本地和远程存储库。我们还可以使用它来存储我们在源代码中不需要的设置，例如凭据。

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

2. 配置

settings.xml 文件配置Maven安装。它类似于 pom.xml 文件，但是全局定义的或每个用户定义的。

让我们探讨一下可以在 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 https://maven.apache.org/xsd/settings-1.0.0.xsd">
    <localRepository/>
    <interactiveMode/>
    <offline/>
    <pluginGroups/>
    <servers/>
    <mirrors/>
    <proxies/>
    <profiles/>
    <activeProfiles/>
</settings>

2.1.简单的价值观

一些顶级配置元素包含简单的值：

<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 元素指向系统本地存储库的路径。 本地存储库是缓存我们项目中所有依赖项的地方 。默认是使用用户的主目录。但是，我们可以更改它以允许所有登录用户从公共本地存储库进行构建。

InteractiveMode 标志定义我们是否允许 Maven 与请求输入的用户进行交互。该标志默认为 true 。

离线 标志确定构建系统是否可以在离线模式下运行。默认为 false； 但是，如果构建服务器无法连接到远程存储库，我们可以将其切换为 true 。

2.2.插件组

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>

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

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

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

2.3.代理

我们可以为 Maven 的部分或全部 HTTP 请求配置代理。 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>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>

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

2.4.镜子

存储库可以在项目 pom.xml 中声明。 这意味着共享项目代码的开发人员可以立即获得正确的存储库设置。

当我们想要为特定存储库 定义 替代镜像 时，我们可以使用镜像。这会覆盖 pom.xml 中的内容。

例如，我们可以通过镜像所有存储库请求来强制 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>

我们可以为给定的存储库仅定义一个镜像，Maven 将选择第一个匹配项。通常， 我们应该使用通过 CDN 分布在全球的官方存储库 。

2.5.服务器

在项目 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>

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

3. 简介

profile 元素使我们能够创建多个 配置 文件子元素，通过其 ID 子元素进行区分。 settings.xml 中的 profile 元素是 pom.xml 中相同元素的截断版本。

它只能包含四个子元素： activation 、 repositories 、 pluginRepositories 和 properties。 这些元素将构建系统配置为一个整体，而不是任何特定的项目。

请务必注意， settings.xml 中活动配置文件中的值将 覆盖 pom.xml 或 profiles.xml 文件中的任何等效配置文件值。配置文件通过 ID 进行匹配。

3.1.激活

我们只能在特定情况下使用配置文件来修改某些值。我们可以使用 激活 元素来指定这些情况。因此， 当满足所有指定条件时，配置文件就会激活 ：

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

有四种可能的激活器，并非所有激活器都需要指定：

  • jdk： 根据指定的JDK版本激活（支持范围）
  • os： 根据操作系统属性激活
  • property： 如果 Maven 检测到特定属性值，则激活配置文件
  • 文件： 如果给定文件名存在或丢失，则激活配置文件

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

mvn help:active-profiles

输出将显示给定项目当前活动的配置文件：

[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.特性

Maven 属性可以被视为特定值的命名占位符。 可以使用 ${property_name} 表示法在 pom.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">
    <profiles>
        <profile>
            <id>baeldung-test</id>
            <properties>
                <user.project.folder>${user.home}/baeldung-tutorials</user.project.folder>
            </properties>
        </profile>
    </profiles>
</settings>

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

  • 使用 env 前缀的属性返回环境变量值，例如 *${env.*PATH}。
  • 使用 项目 前缀的属性返回在 pom.xml 的 项目 元素中设置的属性值，例如 ${project.version}。
  • 使用 设置 前缀的属性从 settings.xml 返回相应元素的值，例如 ${settings.localRepository}。
  • 我们可以通过Java中的 System.getProperties 方法直接引用所有可用的属性，例如 ${java.home}。
  • 我们可以使用不带前缀的 属性 元素中设置的属性，例如 ${junit.version}。

3.3.存储库

远程存储库包含 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>

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

3.4.插件存储库

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>

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

3.5.活动档案

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>

在此示例中，每次调用 mvn 时都会像我们在命令行中添加 -P baeldung-test,adobe-public 一样运行。

4. 设置级别

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

  • Maven 主目录中的全局设置： ${maven.home}/conf/settings.xml
  • 用户家中的用户设置： ${user.home}/.m2/settings.xml

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

4.1.确定文件位置

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

$ mvn -X clean | grep "settings"

4.2.确定有效设置

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

mvn help:effective-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">
    <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.覆盖默认位置

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

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

我们还可以使用同一命令的较短的 –s 版本：

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

5. 结论

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

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

最后，我们着眼于确定所使用的有效设置，并覆盖默认文件位置。