Java Maven Settings配置参考

2023-07-24 00:38 由授客发表于 #后端开发

介绍

快速概览

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的内容可以使用以下表达式进行插值(interpolated)：

1.${user.home}和所有其他系统属性（自Maven 3.0以来）

2.${env.HOME}等环境变量

请注意，在settings.xml 中的profiles中定义的属性不能用于插值。

一个简单配置示例

<?xml version="1.0" encoding="UTF-8" ?>
<settings xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.1.0 http://maven.apache.org/xsd/settings-1.1.0.xsd" xmlns="http://maven.apache.org/SETTINGS/1.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <localRepository>D:\maven-repo</localRepository>
    <servers>
        <server>
            <username>testUser</username>
            <password>APBNwz5vH2BK2Et9ujKQsWQQ245</password>
            <id>central</id>
        </server>
        <server>
            <username>testUser</username>
            <password>APBNwz5vH2BK2Et9ujKQsWQQ245</password>
            <id>snapshots</id>
        </server>
    </servers>
    <mirrors>
        <mirror>
            <mirrorOf>*</mirrorOf>
            <name>maven</name>
            <url>https://artifactory.example.com/artifactory/maven</url>
            <id>maven</id>
        </mirror>
    </mirrors>
    <profiles>
        <profile>
            <repositories>
                <repository>
                    <id>nexus-aliyun</id>
                    <name>nexus-aliyun</name>
                    <url>http://maven.aliyun.com/nexus/content/groups/public/</url>
                    <releases>
                        <enabled>true</enabled>
                    </releases>
                    <snapshots>
                        <enabled>false</enabled>
                    </snapshots>
                </repository>

                <repository>
                    <snapshots>
                        <enabled>false</enabled>
                    </snapshots>
                    <id>central</id>
                    <name>maven</name>
                    <url>https://artifactory.example.com/artifactory/maven</url>
                </repository>
                <repository>
                    <snapshots />
                    <id>snapshots</id>
                    <name>maven</name>
                    <url>https://artifactory.example.com/artifactory/maven</url>
                </repository>
            </repositories>
            <pluginRepositories>
                <pluginRepository>
                    <id>alimaven</id>
                    <name>aliyun maven</name>
                    <url>http://maven.aliyun.com/nexus/content/groups/public/</url>
                </pluginRepository>
                <pluginRepository>
                    <snapshots>
                        <enabled>false</enabled>
                    </snapshots>
                    <id>central</id>
                    <name>maven</name>
                    <url>https://artifactory.example.com/artifactory/maven</url>
                </pluginRepository>
                <pluginRepository>
                    <snapshots />
                    <id>snapshots</id>
                    <name>maven</name>
                    <url>https://artifactory.example.com/artifactory/maven</url>
                </pluginRepository>
            </pluginRepositories>
            <id>artifactory</id>
        </profile>
        <profile>
            <id>jdk-1.8</id>
            <activation>
                <activeByDefault>true</activeByDefault>
                <jdk>1.8</jdk>
            </activation>
            <properties>
                <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
                <maven.compiler.source>1.8</maven.compiler.source>
                <maven.compiler.target>1.8</maven.compiler.target>
                <maven.compiler.compilerVersion>1.8</maven.compiler.compilerVersion>
            </properties>
        </profile>
    </profiles>
    <activeProfiles>
        <activeProfile>artifactory</activeProfile>
    </activeProfiles>
</settings>

Settings明细

简单值

顶级settings 元素的一半是简单值，表示一系列值，这些值描述了构建系统中一直处于激活(active full-time)的元素

<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。默认为false。该元素对于由于网络设置或安全原因而无法连接到远程仓库的服务器构建非常有用。

插件组(Plugin Groups)

此元素包含一个 pluginGroup 元素列表，每个元素都包含一个组ID。当用到某个插件并且命令行中没有提供该插件组件ID时，会搜索该列表。此列表自动包含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

服务器(Servers)

由POM的repositions和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 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: 这是与Maven试图连接的，与仓库/镜像的 id 元素匹配的服务器（而不是要登录的用户）的ID。
username, password: 这两元素成对出现，分别表示对此服务器进行身份验证所需的登录名和密码。
privateKey, passphrase: 类似前两个元素，这对元素指定私钥（默认为 ${user.home}/.ssh/id_dsa）和passphrase的路径，如果必要的话。passphrase 和password元素将来可能会外部化，但目前它们必须在settings.xml文件中设置为纯文本。
filePermissions, directoryPermissions: 在发布时创建仓库文件或目录时，需要使用的权限。每个的合法值是一个三位数，对应于*nix文件权限，例如664或775。

注意：如果使用私钥登录服务器，请确保省略<password> 元素。否则，该键将被忽略。

密码加密

2.1.0+中添加了一项新功能-服务器密码和passphrase加密。详情请查阅https://maven.apache.org/guides/mini/guide-encryption.html

镜像(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用于区分mirror元素，以及连接到镜像时，用于从servers 中选择相应的凭据。
url: 镜像的基础URL。构建系统将使用此URL连接到仓库，而不是原始仓库的URL。
mirrorOf: 设置要被镜像的仓库id。例如，如需指向Mavencenter仓库(https://repo.maven.apache.org/maven2/)的镜像，设置该元素值为center。更高级的映射，如repo1，repo2或*,!inhouse也是可以的。该配置值一定与镜像id不同。

有关镜像的更深入介绍，请阅读镜像设置指南

镜像设置指南

为仓库使用镜像

拥有仓库，你可以指定要从哪个位置下载某些工件，例如依赖项和maven插件。可以在项目内部声明仓库，这意味着，如果你有自己的自定义仓库，那些共享你项目的可以很容易地获得开箱即用的正确配置。但是，你可能希望在不更改项目文件的情况下为特定仓库使用备用镜像。

使用镜像的一些原因是：

互联网上有一个同步镜像，地理位置更近、速度更快
希望用自己的内部仓库替换特定的仓库，可以对其进行更大的控制
想运行仓库管理器为镜像提供本地缓存，而需要使用其URL

可以简单的把mirror理解为一个拦截器，拦截maven对远程repository的相关请求，然后把请求里的remote repository地址，重定向到mirror里配置的地址，如下

未配置镜像前：

配置镜像之后：

要为给定仓库配置镜像，需在配置文件(${user.home}/.m2/settings.xml)中提供它，为新仓库指定自己的id和url，并指定mirrorOf设置，即被镜像的仓库ID。例如，默认情况下包含的Maven Central主仓库的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不会聚合镜像，而是简单地选择第一个匹配的镜像。如果要提供多个仓库的组合视图，请使用仓库管理器。

settings.xml述符文档查阅https://maven.apache.org/ref/3.9.3/maven-settings/settings.html

注：Maven的官方仓库位于https://repo.maven.apache.org/maven2由Sonatype公司托管，并通过CDN在全球范围内分发。

仓库Metadata中提供了已知镜像的列表。这些镜像可能没有相同的内容，我们不以任何方式支持它们。

使用单个仓库

可以通过让Maven镜像所有仓库请求来强制它使用单个仓库。仓库必须包含所有所需的工件，或者能够将请求代理到其他仓库。当使用具有代理外部请求的Maven 仓库管理器的内部公司仓库时，此设置最有用。

为此，请将 mirrorOf设置为*。

注意：此功能仅在Maven 2.0.5+中可用。

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

高级设置

单个镜像可以处理多个仓库。这通常与仓库管理器结合使用，后者可以方便地集中配置镜像背后的仓库列表。

语法：

*匹配所有仓库ID。
external:*匹配除使用localhost或基于文件的仓库以外的所有仓库。当希望排除为集成测试定义的重定向仓库时，使用此选项。
从Maven 3.8.0开始， external:http:* 匹配使用localhost除外，所有使用HTTP的仓库
可以使用逗号作为分隔符指定多个仓库
感叹号可以与上述通配符之一一起使用，以排除仓库id

注意不要在逗号分隔列表中的标识符或通配符周围包含额外的空格。例如，将<mirrorOf>设置为!repo1, *不会镜像任何内容，而!repo1,*将镜像除repo1之外的所有内容。

通配符在以逗号分隔的仓库标识符列表中的位置并不重要，因为通配符会推迟进一步处理，并且显式包含或排除会停止处理，从而否决任何通配符匹配(原文：The position of wildcards within a comma separated list of repository identifiers is not important as the wildcards defer to further processing and explicit includes or excludes stop the processing, overruling any wildcard match)。

当您使用高级语法并配置多个镜像时，声明顺序很重要。当Maven查找某个仓库的镜像时，它首先检查<mirrorOf>与仓库标识符完全匹配的镜像。如果没有找到直接匹配，Maven会根据上面的规则（如果有的话）选择第一个匹配的镜像声明。因此，可以通过更改settings.xml中定义的顺序来影响匹配顺序

示例：

*=所有仓库
external:*=所有不在本地主机上且不基于文件的内容。
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>

创建自己的镜像

central仓库的大小正在稳步增加。为了节省带宽和你的时间，不允许镜像整个central仓库(如果这样做会被自动禁止）相反，建议设置一个仓库管理器作为代理。

代理(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: 此代理的唯一标识符。这用于区分proxy 元素。
active: true 如果此代理处于活动状态，则为true 。这对于声明一组代理很有用，但一次只能有一个代理处于活动状态。
protocol, host, port: 代理的 protocol://host:port，分隔成单个元素
username, password: 这些元素成对出现，表示对此代理服务器进行身份验证所需的登录名和密码
nonProxyHosts: 这是不应使用代理的主机列表。列表的分隔符是代理服务器的预期类型；上面的例子是管道分隔的，逗号分隔也是常见的。

Profiles

settings.xml中的profile 元素是 pom.xml profile 元素的“裁剪”版本。它由activation, repositories, pluginRepositories 和 properties 元素组成。 profile元素只包括这四个元素，因为它们关注的是整个构建系统（即settings.xml文件的作用），而不是单个项目对象模型设置。

如果一个settings.xml中的profile被激活，它的值会覆盖任何其它定义在pom.xml或profiles.xml中带有相同ID的profile。

Activation

Activations是配置文件的关键。与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 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>

当满足所有指定的条件时，将激活profile，但并非需要同时满足所有条件。

jdk：activation在 jdk 元素中有一个内置的、以Java为中心的检查。如果在与给定版本前缀匹配的jdk版本号下运行测试，这将激活profile。在上面的示例中，1.5.0_06将匹配给定前缀即1.5。也支持范围。请参阅maven enforcer插件获取有关支持范围的更多详细信息。
os：os元素可以定义上面显示的一些特定于操作系统的属性。请参阅maven enforcer插件获取有关操作系统值的更多详细信息。
property：如果Maven检测到相应的name=value 对的属性（一个可以在pom.xml中通过 ${name}间接引用的值），则 profile 将被激活。
file：最后，可通过给定文件名对应文件的 existence 或者missing激活 profile

activation 元素并不是激活profile的唯一方式。 settings.xml文件的activeProfile 元素可能包含profile的id。它们也可以通过命令行，通过 -P 标志后的逗号分隔列表（例如 -P test）显式激活。

要查看哪个配置文件将在某个构建中激活，请使用maven-help-plugin。

mvn help:active-profiles

属性(Properties)

Maven properties是值占位符，类似于Ant中的properties。通过使用表示法 ${X}，可以在POM中的任何位置访问它们的值，其中 X 是属性。它们有五种不同的形式，都可以从settings.xml文件中访问：

env.X: 在变量前面加上“env.”前缀，将返回shell的环境变量。例如，${env.PATH} 包含$path环境变量（在Windows中为%PATH%）。
project.x: POM中.分路径包含相应元素的值。例如：可通过 ${project.version}获取1.0。
settings.x: settings.xml 中的.分路径包含相应元素的值。例如可通过${settings.offline}得到false 值。
Java 系统属性: 所有属性，可通过java.lang.System.getProperties() 获取并可作为POM properties，比如 ${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>

如果profile被激活的话，可通过POM访问属性${user.install}

仓库(Repositories)

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 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: 这些是针对每种类型的工件，Release 或snapshot的策略。有了这两个集合，POM就有能力在单个仓库中独立于其他类型来更改每种类型的策略。例如，可能出于开发目的，可以决定只启用snapshot下载。
enabled: true or false ，以确定是否为相应类型（releases or snapshots）启用此仓库。
updatePolicy: 此元素指定尝试进行更新的频率。Maven将本地POM的时间戳（存储在仓库的Maven元数据文件中）与远程POM进行比较。选项为： always, daily (默认)、或者interval:X（其中X是以分钟为单位的整数）或never。
checksumPolicy: 当Maven将文件发布到仓库时，它还会发布相应的校验和文件。关于丢失或不正确的校验和时，可以选择 ignore、fail或 warn 。
layout: 在上面对仓库的描述中，有人提到它们都遵循一个通用的布局。这基本上是正确的。Maven2有一个默认的仓库布局；然而，Maven1.x有一个不同的布局。使用此元素指定是default还是 legacy

插件仓库(Plugin Repositories)

仓库是两种主要类型的工件的所在地。第一种是用作其他工件的依赖项的工件。这些是位于中心的大多数工件。另一种类型的工件是插件。Maven插件本身就是一种特殊类型的工件。正因为如此，插件仓库可能会与其他仓库分离（尽管，我还没有听到这样做的令人信服的论据）。在任何情况下， pluginRepositories 元素块的结构都类似于 repositories 元素。 pluginRepository元素分别指定Maven可以在其中查找新插件的远程位置。

激活Profiles(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 元素。它包含一系列activeProfiles 元素，每个元素的值都有一个 profile id。任何定义为activeProfile的profile id 都将处于活动状态，而与任何环境设置无关。如果没有找到匹配的profile，则什么也不会发生。例如，如果env-test为一个activeProfile，一个在具有相应id的pom.xml（或profile.xml）将处于活动状态。如果找不到这样的profile，则执行将照常进行。

参考链接

https://maven.apache.org/settings.html

https://maven.apache.org/ref/3.9.3/maven-settings/settings.html