Maven settings.xml文件详解

qq_547026179

11745人浏览 · 2024-01-18 23:58:58

qq_547026179 · 2024-01-18 23:58:58 发布

一、settings.xml 简介

settings.xml文件是 Maven 的核心配置文件之一，用于配置 Maven 工具本身的行为。这个文件包含了Maven的一些高级配置，比如本地仓库的位置、代理设置、认证信息等。settings.xml文件通常位于以下两个位置：

全局配置（所有用户生效）
```
Maven安装目录/conf/settings.xml
```

用户配置（当前用户生效，优先级更高）

~/.m2/settings.xml （Linux/Mac）
C:\Users\用户名\.m2\settings.xml （Windows）

在使用 Maven 的时候如果未指定settings.xml文件的位置，默认使用的是用户目录下面的.m2子目录中的settings.xml文件。

二、与 pom.xml 文件区别

settings.xml：用户/全局级配置文件。它用来配置 Maven 运行的环境本身，如本地仓库位置、网络代理、远程仓库认证信息、激活不同的 profile（如开发/生产环境）等。通常不提交到版本库，因为它包含个人或本地环境的特定设置。
pom.xml ：项目级配置文件。它定义了项目信息、依赖、插件、构建生命周期等。提交到版本控制系统，与项目成员共享。

三、配置文件位置与优先级

Maven 会按以下顺序查找并合并 settings.xml（后者覆盖前者）：

全局设置：${M2_HOME}/conf/settings.xml
- Maven 安装目录下的配置，影响所有使用该 Maven 的用户。
- 需要管理员权限修改。
用户设置：${user.home}/.m2/settings.xml
- 用户家目录下的 .m2 文件夹中。
- 这是最常用、最推荐自定义的位置。你可以复制全局的 settings.xml 到这里进行修改。
指定位置：通过命令行参数 -s /path/to/settings.xml 指定。
- 用于特殊场景，如 CI/CD 流水线中指定一个特定的配置文件。

四、settings.xml 主要结构

settings.xml 文件包含以下主要部分：

<?xml version="1.0" encoding="UTF-8"?>
<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
                              http://maven.apache.org/xsd/settings-1.0.0.xsd">
  <!-- 本地仓库路径 -->
  <localRepository>/path/to/your/local/repo</localRepository>

  <!-- 交互模式：true 表示 Maven 会提示输入，false 则不会（适用于 CI） -->
  <interactiveMode>true</interactiveMode>

  <!-- 离线模式：true 表示只使用本地仓库，不联网 -->
  <offline>false</offline>

  <!-- 插件组：为插件指定默认的 groupId，执行时可以不写 groupId -->
  <pluginGroups>
    <pluginGroup>org.eclipse.jetty</pluginGroup>
  </pluginGroups>

  <!-- 服务器认证信息（私服、发布仓库等） -->
  <servers>
    <server>
      <id>my-company-repo</id> <!-- 必须与 pom.xml 或镜像中配置的 repository/id 匹配 -->
      <username>deploy-user</username>
      <password>encrypted_password_here</password>
      <!-- 可选：私钥路径和密码短语，用于 SSH 认证 -->
      <!-- <privateKey>/path/to/private/key</privateKey> -->
      <!-- <passphrase>key_passphrase</passphrase> -->
    </server>
  </servers>

  <!-- 镜像：用指定的仓库替换指定的远程仓库，常用于加速或内网私服 -->
  <mirrors>
    <mirror>
      <id>aliyun-maven</id>
      <name>Aliyun Maven Mirror</name>
      <url>https://maven.aliyun.com/repository/public</url>
      <mirrorOf>central</mirrorOf> <!-- 匹配 central 仓库的请求都走这个镜像 -->
      <!-- mirrorOf 可以是：*（全部）、external:*（除本地文件系统和 localhost 外的所有）、
           repo1,repo2（多个仓库）、*,!repo1（全部除 repo1） -->
    </mirror>
  </mirrors>

  <!-- 代理设置 -->
  <proxies>
    <proxy>
      <id>my-proxy</id>
      <active>true</active>
      <protocol>http</protocol>
      <host>proxy.mycompany.com</host>
      <port>8080</port>
      <username>proxyuser</username>
      <password>proxypass</password>
      <nonProxyHosts>localhost|127.0.0.1|*.mycompany.com</nonProxyHosts>
    </proxy>
  </proxies>

  <!-- 配置文件组：用于定义一组可激活的条件和属性，非常灵活 -->
  <profiles>
    <profile>
      <id>jdk-11</id>
      <activation>
        <!-- 激活条件：当检测到 JDK 版本为 11 时自动激活 -->
        <jdk>11</jdk>
      </activation>
      <properties>
        <!-- 定义属性，可以在 pom.xml 中用 ${maven.compiler.source} 引用 -->
        <maven.compiler.source>11</maven.compiler.source>
        <maven.compiler.target>11</maven.compiler.target>
      </properties>
    </profile>
    <profile>
      <id>company-nexus</id>
      <repositories>
        <repository>
          <id>company-releases</id>
          <url>https://nexus.mycompany.com/repository/maven-releases/</url>
          <releases><enabled>true</enabled></releases>
          <snapshots><enabled>false</enabled></snapshots>
        </repository>
        <repository>
          <id>company-snapshots</id>
          <url>https://nexus.mycompany.com/repository/maven-snapshots/</url>
          <releases><enabled>false</enabled></releases>
          <snapshots><enabled>true</enabled></snapshots>
        </repository>
      </repositories>
      <pluginRepositories>
        <!-- 类似地配置插件仓库 -->
      </pluginRepositories>
    </profile>
  </profiles>

  <!-- 激活的配置文件列表。定义在 profiles 中的 profile 需要在这里激活才会生效 -->
  <activeProfiles>
    <activeProfile>company-nexus</activeProfile> <!-- 默认激活公司私服配置 -->
    <!-- <activeProfile>jdk-11</activeProfile> --> <!-- 这个会根据条件自动激活，无需显式声明 -->
  </activeProfiles>
</settings>

4.1 settings.xml 文件中常用的顶级元素

<?xml version="1.0" encoding="UTF-8"?>
<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 http://maven.apache.org/xsd/settings-1.0.0.xsd">
  
  <localRepository></localRepository>
  <interactiveMode></interactiveMode>
  <offline></offline>
  <pluginGroups></pluginGroups>
  <proxies></proxies>
  <servers></servers>
  <mirrors></mirrors>
  <profiles></profiles>
  <activeProfiles></activeProfiles>
</settings>

4.2 LocalRepository

<localRepository>元素用于指定Maven本地仓库的路径。当Maven在进行构建时用于查找和存储项目依赖的位置。默认情况下，Maven的本地仓库路径是~/.m2/repository中，可以通过<localRepository>元素来设置其他的本地仓库路径，具体配置如下：

<localRepository>/path/to/local/repo</localRepository>

4.3 InteractiveMode

<interactiveMode>元素用于控制Maven的交互模式。当<interactiveMode>元素被设置为true时，Maven在执行构建过程时会显示进度条并等待用户的输入。当<interactiveMode>元素被设置为false时，Maven在执行构建过程时不会显示进度条，也不会等待用户的输入，而是会立即开始构建过程。默认情况下，Maven的<interactiveMode>元素的值是true；有些特殊场景，例如在自动化构建过程中不需要进行交互模式，这时我们可以将<interactiveMode>元素的值设置为false。

<interactiveMode>false</interactiveMode>

4.4 offline

<offline>元素用于控制Maven是否在离线模式下工作。默认是false，使用在线模式，Maven在执行构建过程时会从远程仓库下载依赖，而不会从本地仓库查找和使用依赖。当<offline>元素被设置为true时，使用离线模式，Maven在执行构建过程时只会从本地仓库查找和使用依赖，不会从远程仓库下载依赖。在某些情况下，我们可能希望Maven在执行构建过程时不从远程仓库下载依赖，例如在网络不稳定或没有网络连接时。这时，我们可以将<offline>元素的值设置为true。

<offline>true</offline>

4.5 pluginGroups

<pluginGroups>元素用于定义Maven插件搜索的组。Maven会根据<pluginGroups>元素中定义的组来搜索和加载相关的插件。<pluginGroups>元素是一个列表，每个元素都包含一个<pluginGroup>元素，用于指定一个或多个插件组的名称。插件组是一组相关的插件，它们通常被组织在一起，以便在构建项目时能够方便地使用。

<settings>
 <pluginGroups>
 	<pluginGroup>com.example.plugins</pluginGroup>
 </pluginGroups>
 ...
</settings>

4.6 proxies

<proxies>元素用于配置Maven的代理设置。通过代理设置允许Maven通过代理服务器访问互联网，这对于在某些网络环境下构建项目非常有用。<proxies>元素是一个列表，每个元素都包含一个<proxy>元素，用于指定一个代理服务器的详细信息。<proxy>元素包含以下属性：

id：代理的唯一定义符，用来区分不同的代理元素。
active：该代理是否激活。true则激活代理；如果你不需要使用代理，可以将active设置为false。
protocol：代理服务器使用的协议。（如http或https）
host：代理服务器的主机名或IP地址。
port：代理服务器的端口号。
username（可选）：代理服务器的用户名。
password（可选）：代理服务器的密码。
nonProxyHosts（可选）：指定哪些主机不使用代理服务器。

<settings>
 <proxies>
 	<proxy>
   		<id>proxy-name</id>
   		<active>true</active>
   		<protocol>http</protocol>
   		<host>proxyhost</host>
   		<port>8080</port>
   		<username>proxyuser</username>
   		<password>proxypassword</password>
   		<nonProxyHosts>localhost|*.example.com</nonProxyHosts>
 	</proxy>
 </proxies>
 ...
</settings>

4.7 servers

<servers>元素用于定义远程仓库的服务器信息。这些远程仓库可以是中央仓库或者是团队内部的私有仓库。Maven在进行构建时，会从这些远程仓库中查找和下载项目依赖。有些远程仓库下载依赖时是需要安全认证的，这些安全认证的信息就是在<server>元素中设置的。<server>元素包含以下属性：

id：定义服务器的唯一标识符。
url：远程仓库的URL地址。
username：访问远程仓库时使用的用户名。
password：访问远程仓库时使用的密码。

<settings>
 <servers>
 <server>
   <id>sonatype-nexus-releases</id>
   <username>admin</username>
   <password>admin123</password>
   <url>http://nexus.sonatype.org/content/repositories/releases/</url>
 </server>
 </servers>
 ...
</settings>

4.8 mirrors

<mirrors>元素用于配置Maven的镜像仓库。镜像仓库是一个本地的、用于存储远程仓库内容的缓存。Maven会首先尝试从远程仓库下载依赖，如果远程仓库不可用或访问受限，Maven就会从镜像仓库获取依赖。<mirrors>元素是一个列表，每个元素都包含一个<mirror>元素，用于指定一个镜像仓库的服务器信息。一个<mirror>元素包含如下属性：

id：定义镜像仓库的唯一标识符。
url：镜像仓库的URL地址。
active：镜像仓库是否处于活动状态。
mirrorOf：要被镜像的远程仓库的ID。当远程仓库被镜像后，后续将不会再从这个远程仓库去拉取依赖，而是直接从镜像仓库的地址去拉取依赖。如果mirrorOf里面配置的是*，则配置的所有远程仓库都被镜像，任何项目所需的依赖都只会从这个镜像的地址中拉取。

<settings>
 <mirrors>
 <mirror>
   <id>nexus-mirror</id>
   <url>http://nexus.example.com/content/repositories/releases/</url>
   <mirrorOf>central</mirrorOf>
 </mirror>
 <mirror>
   <id>sonatype-oss-mirror</id>
   <url>http://oss.sonatype.org/content/repositories/releases/</url>
   <mirrorOf>central</mirrorOf>
 </mirror>
 </mirrors>
 ...
</settings>

4.9 profiles

<profiles>元素用于定义项目构建过程中使用的配置文件。这些配置文件可以在不同的环境中使用，例如开发环境和生产环境。<profiles>元素允许你为不同的环境定义不同的配置文件，从而实现环境之间的差异性。<profiles>元素是一个列表，每个元素都包含一个<profile>元素，用于定义一个全局级别的配置信息。一个<profile>元素包含如下属性：

id：定义配置信息的唯一标识符。
properties：配置文件的属性列表。
activation：激活配置文件所需的条件。
description：配置文件的描述信息。
repositories：远程仓库列表。
pluginRepositories：插件仓库列表。

<settings>
 <profiles>
 <profile>
   <id>dev</id>
   <properties>
    <myProperty>myValue</myProperty>
   </properties>
   <activation>
    <build>
     <property>
      <myProperty>myValue</myProperty>
     </property>
    </build>
   </activation>
 </profile>
 </profiles>
 ...
</settings>

pom.xml中的profile作用于当前的Maven项目，settings.xml中的profile作用于Maven的全局设置。settings.xml中的profile优先级高于pom.xml中的profile，当Maven在构建过程中遇到profile时，它会首先查找settings.xml文件中的profile，如果找到了，则使用该profile中的设置。如果settings.xml文件中没有找到，Maven才会继续在pom.xml文件中查找profile。如果在pom.xml中也定义了一个同名的profile，那么settings.xml中的profile将覆盖pom.xml中的profile。因此，为了确保profile的正确使用，建议在settings.xml中定义全局的profile设置，并在pom.xml中只使用项目特定的profile设置。

4.10 activeProfiles

<activeProfiles>元素用于指定哪些profile在当前的构建过程中被激活。每个<activeProfiles>元素可以包含一个或多个<profile>元素，每个<profile>元素都有一个id属性，用于标识该profile。当Maven在构建过程中遇到<activeProfiles>元素时，它会检查当前的构建环境是否与<activeProfiles>元素中指定的任何profile相匹配。如果匹配，则该profile被激活，并应用于当前的构建过程。

<settings>
 <activeProfiles>
 	<profile>
   		<id>dev</id>
 	</profile>
 </activeProfiles>
 ...
</settings>

科技创新，汇聚千年文化底蕴，共筑璀璨首都未来之梦！

欢迎加入北京社区

更多推荐

小白也能丝滑入手浏览器自动抓取可用数据

北京城市开发者社区

Bright Data Web MCP深度测评：与Claude Code集成，企业级百万级数据采集实战

北京城市开发者社区

告别大模型API选型焦虑：AI Ping实战体验与深度评测

北京城市开发者社区

所有评论(0)

查看更多评论

qq_547026179

@qq_33807380

已为社区贡献1条内容