Maven的settings.xml介绍

最新推荐文章于 2024-06-09 21:34:22 发布

javajingling

最新推荐文章于 2024-06-09 21:34:22 发布

阅读量1.3k

点赞数 19

分类专栏：项目构建工具文章标签： maven

本文链接：https://blog.csdn.net/javajingling/article/details/135502658

版权

项目构建工具专栏收录该内容

3 篇文章 0 订阅

订阅专栏

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

介绍

简要介绍

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

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

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

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

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

如果此配置文件处于活动状态，则可以从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）将是活动的。如果没有找到这样的配置文件，则执行将继续正常进行。