Maven的settings.xml介绍

以下内容为官网内容翻译。原文入口

介绍

简要介绍

​ settings.xml 文件中的 settings 元素包含用于定义配置 Maven 执行方式的值的元素，类似于 pom.xml，但不应捆绑到任何特定项目，也不应分发给任何用户。其中包括本地仓库位置、备用远程仓库服务器和身份验证信息等值。

​ settings.xml 文件可以存在于两个位置：

1. Maven 安装目录： ${maven.home}/conf/settings.xml
2. 用户安装目录： ${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 插件。仓库可以在项目内声明，这意味着如果您有自己的自定义仓库，那些与您的项目共享的人可以轻松地获得正确的设置。但是，您可能希望在不更改项目文件的情况下为特定仓库使用替代镜像。

使用镜像的一些原因包括：

1. 有一个在互联网上同步的镜像，地理位置更近，速度更快
2. 您想要用您有更大控制权的内部仓库替换特定的仓库
3. 您想要运行一个仓库管理器，为镜像提供本地缓存，并需要使用其 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文件中访问：

1. env.X: 在变量前加上“env.”将返回shell的环境变量。例如，${env.PATH}包含$path环境变量（在Windows中为%PATH%）。
2. project.x: POM中的点（.）标记路径将包含相应元素的值。例如：<project><version>1.0</version></project>可以通过${project.version}访问。
3. settings.x: settings.xml中的点（.）标记路径将包含相应元素的值。例如：<settings><offline>false</offline></settings>可以通过${settings.offline}访问。
4. Java系统属性: 通过java.lang.System.getProperties()可访问的所有属性都作为POM属性可用，例如${java.home}。
5. 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）将是活动的。如果没有找到这样的配置文件，则执行将继续正常进行。