1. 概述

使用 Maven 时,我们将大部分与项目有关的配置保留在 pom.xml 中。

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

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

2. settings.xml 配置项详解

settings.xml 在 Maven 安装目录下的 conf 下,主要包含 9 项顶级配置:

<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 元素指向本地仓库缓存路径,默认是使用用户的home目录。

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

offline 标志确定构建系统是否可以在离线模式下运行。默认为 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.pluginsorg.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>

我们通过 active 标志定义当前活动的代理。然后使用 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

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

它只能包含四个子元素: activationrepositoriespluginRepositoriesproperties。 这些元素将构建系统配置为一个整体,而不是任何特定的项目。

请务必注意, settings.xml 中活动配置文件中的值将 覆盖 pom.xmlprofiles.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. Properties

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 文件中可用的配置

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

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