当前位置：首页 > news >正文

Maven 详细配置：Maven settings 配置文件的详细说明

news 2025/11/10 20:18:32

Maven settings 配置文件是 Maven 环境的重要组成部分，它用于定义用户特定的配置信息和全局设置，例如本地仓库路径、远程仓库镜像、代理服务器以及认证信息等。settings 文件分为全局配置文件（settings.xml）和用户配置文件（用户目录下的 .m2/settings.xml），它们分别影响 Maven 的全局行为和当前用户的个性化配置。通过合理配置 settings 文件，开发者可以优化构建性能、提升依赖解析效率，并满足企业开发环境中的特殊需求。本篇内容将深入解析 settings 文件的结构和使用方法，帮助读者灵活定制 Maven 环境，提升项目开发效率和稳定性。

文章目录

- - 1、关于 Settings 配置文件
  - 2、Settings 顶级元素的详细介绍
  - - 2.1、简单值元素
    - 2.2、插件组元素
    - 2.3、服务器配置元素
    - 2.4、镜像仓库元素
    - 2.5、代理元素
    - 2.6、构建配置元素
    - 2.7、激活的构建配置元素

1、关于 Settings 配置文件

在 Maven 官网，关于 Settings 配置文件说明：https://maven.apache.org/settings.html

在 settings.xml 文件中的 settings 元素包含了一些用于定义配置 Maven 执行方式的值，类似于 pom.xml，但这些配置不应绑定到任何特定项目，也不应该分发给其他用户。这些配置包括本地仓库的位置、备用的远程仓库服务器以及认证信息等。

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

Maven 安装目录：${maven.home}/conf/settings.xml
用户目录：${user.home}/.m2/settings.xml

第一个位置的 settings.xml 称为全局设置（Global Settings），第二个位置的 settings.xml 称为用户设置（User Settings）。如果两个文件同时存在，它们的内容会被合并，其中用户设置优先级更高。

2、Settings 顶级元素的详细介绍

下面是一份位于 POM 文件中 <settings> 元素下的元素列表（截图自官网）：

2.1、简单值元素

对于 Maven 的 Settings 文件来说，一半的顶级元素（Root Element）都是简单值元素，这些简单值用于描述构建系统中一些始终处于活跃状态的配置项。

<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><usePluginRegistry>false</usePluginRegistry><offline>false</offline>...
</settings>

配置说明：

顶级元素 localRepository：本地仓库。该值表示构建系统本地仓库的路径。其默认值为 ${user.home}/.m2/repository 。
顶级元素 interactiveMode：Maven 是否需要和用户交互以获得输入。如果 Maven 需要和用户交互以获得输入，则设置成 true，反之则应为 false。其默认值为 true。
顶级元素 usePluginRegistry：Maven 是否需要使用 plugin-registry.xml 文件来管理插件版本。如果设置为 true，则在{user.home}/.m2 下需要有一个 plugin-registry.xml 来对 plugin 的版本进行管理。默认为 false。（该元素在 Maven 3 中已被废弃）
顶级元素 offline：Maven 是否需要在离线模式下运行。如果构建系统需要在离线模式下运行，则为 true，反之则应为 false。当由于网络设置原因或者安全因素，构建服务器不能连接远程仓库的时候，该配置就十分有用。其默认值为 false。

2.2、插件组元素

此元素包含一个 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.apache.maven.plugins</pluginGroup><pluginGroup>org.codehaus.mojo</pluginGroup></pluginGroups>...
</settings>

配置说明：

顶级元素 pluginGroups：当插件的组织 ID（groupId）没有显式提供时，供搜寻插件组织 ID（groupId）的列表。当我们使用某个插件，并且没有在命令行为其提供组织 ID（groupId）的时候，Maven 就会使用该列表。
一级子元素 pluginGroup：插件的组织 ID（groupId）。

2.3、服务器配置元素

在 Maven 中，用于下载和部署的仓库通过 POM 文件中的 <repositories> 和 <distributionManagement> 元素进行定义。然而，某些敏感信息（如用户名和密码）不应该随 pom.xml 一起分发。这类信息应保存在 settings.xml 中，例如在构建服务器上使用的配置。

以下是一个 servers 配置示例：

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

配置说明：

顶级元素 servers：配置服务端的一些设置。一些设置如安全证书不应该和 pom.xml 一起分发。这种类型的信息应该存在于构建服务器上的 settings.xml 文件中。
一级子元素 server：服务器元素，包含配置服务器时需要的信息。
二级子元素 id：服务器的 ID（注意不是用户登陆的 ID），该 id 与 POM 文件中 distributionManagement/repository 元素的 id 或 Settings 文件中 mirrors/mirror 元素的 id 相匹配。
二级子元素 username、password：鉴权用户名和鉴权密码，表示服务器认证所需要的登录名和密码。
二级子元素 privateKey、passphrase：鉴权时使用的私钥位置和私钥密码。和前两个元素类似，私钥位置和私钥密码指定了一个私钥的路径（默认是 /home/hudson/.ssh/id_dsa）和可选的密钥短语。
二级子元素 filePermissions、directoryPermissions：部署过程中创建的文件或目录的权限设置。这两个元素合法的值是一个三位数字，其对应了 unix 文件系统的权限。
二级子元素 configuration：该元素用于定义服务器相关的其他配置（自定义配置，较少使用）。

PS（注意事项）：① 从 Maven 2.1.0 开始，新增了服务器密码和密钥短语加密的功能，以增强安全性；② 如果使用私钥登录服务器，需要确保省略 password 元素，否则会导致私钥被忽略；③ 在需要同时访问多个远程仓库的项目中，通过 settings.xml 中的 <servers> 元素配置这些仓库的认证信息，避免将敏感信息暴露在 pom.xml 中。

2.4、镜像仓库元素

在 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>alimaven</id><name>aliyun maven</name><url>http://maven.aliyun.com/nexus/content/groups/public/</url><mirrorOf>central</mirrorOf></mirror></mirrors>...
</settings>

配置说明：

顶级元素 mirrors：为仓库列表配置的下载镜像列表。
一级子元素 mirror：给定仓库的下载镜像。
二级子元素 id：该镜像的唯一标识符。用来区分不同的 mirror 元素。
二级子元素 name：镜像名称。
二级子元素 url：该镜像的 URL。构建系统会优先考虑使用该 URL，而非使用默认的服务器 URL。
二级子元素 id：被镜像的服务器的 ID。例如，如果我们要设置了一个 Maven 中央仓库（http://repo1.maven.org/maven2）的镜像，就需要将该元素设置成 central。这必须和中央仓库的 ID - central 完全一致。

2.5、代理元素

在 Maven 的 settings.xml 文件中，可以通过 proxies 元素配置代理服务器，用于在受限制的网络环境中访问外部仓库。

以下是一个 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>

配置说明：

顶级元素 proxies：用来配置不同的代理的列表。
一级子元素 proxy：代理元素，包含配置代理时需要的信息。
二级子元素 id：代理的唯一标识符，用于区分不同的代理配置。
二级子元素 active：该代理是否是激活的那个。true 则激活代理。当我们声明了一组代理，而某个时候只需要激活一个代理的时候，该元素就可以派上用处。
二级子元素 protocol：代理协议，例如 http 或 https。
二级子元素 host、port：代理服务器的主机名或 IP 地址和代理服务器的端口号。
二级子元素 username、 password：代理认证所需的用户名和密码
二级子元素 nonProxyHosts：不需要通过代理访问的主机列表。该列表的分隔符由代理服务器指定，例子中使用了竖线分隔符，使用逗号分隔也很常见。

2.6、构建配置元素

在 settings.xml 文件中的 profile 元素是 pom.xml 文件中 profile 元素的简化版。它仅包含以下几个元素，因为这些元素关注的是整个构建系统的配置，而不是单个项目的设置。

这些元素包括：activation（激活）、repositories（仓库）、pluginRepositories（插件仓库）、properties（属性）。

<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><properties/><repositories/><pluginRepositories/></activation></profile>><activeProfiles><activeProfile>dev</activeProfile></activeProfiles></profiles>...
</settings>

配置说明：

顶级元素 profiles：根据环境参数来调整构建配置的列表。
一级子元素 profile：根据环境参数来调整的构件的配置。
二级子元素 id：该配置的唯一标识符。
二级子元素 activation：自动触发 Profile 的条件逻辑。
三级子元素 activeByDefault：布尔标志，确定 Profile 是否默认处于活动状态。仅当没有其他配置文件通过命令行明确激活或通过其他激活器隐式激活时，才会评估此标志，否则无效。
三级子元素 jdk：当匹配的 JDK 被检测到，Profile 被激活。例如，1.4 激活 JDK1.4，1.4.0_2，而 !1.4激活所有版本不是以 1.4 开头的 JDK。.
三级子元素 os：当匹配的操作系统属性被检测到，Profile 被激活。os 元素可以定义一些操作系统相关的属性
四级子元素 name：激活 Profile 的操作系统的名字。
四级子元素 family：激活 Profile 的操作系统所属家族，如 Windows。
四级子元素 arch：激活 Profile 的操作系统体系结构。
四级子元素 version：激活 Profile 的操作系统版本。
三级子元素 property：如果 Maven 检测到某一个属性（其值可以在 POM 中通过 ${名称} 引用），其拥有对应的名称和值，Profile 就会被激活。
四级子元素 name：激活 Profile 的属性的名称
四级子元素 value：激活 Profile 的属性的值
三级子元素 file：提供一个文件名，通过检测该文件的存在或不存在来激活 Profile。
四级子元素 exists：检查文件是否存在，如果存在则激活 Profile。
四级子元素 missing：检查文件是否存在，如果不存在则激活 Profile。
二级子元素 properties：同 POM 文件中的顶级元素 properties。
二级子元素 repositories：同 POM 文件中的顶级元素 repositories。
二级子元素 pluginRepositories：同 POM 文件中的顶级元素 pluginRepositories。
二级子元素 activeProfiles：定义每个 Profile 内部是否有特定的 Profile 需要激活。这样可以在某些特定的构建配置中嵌套其它的激活配置。
三级子元素 activeProfile：被嵌套激活的 Profile 的 ID。

2.7、激活的构建配置元素

在 Maven 的 settings.xml 文件中，activeProfiles 元素用于指定在构建时要激活的 Maven 配置元素。它允许你在不同的构建环境中自动激活特定的 Profile，而不需要在命令行或 POM 文件中手动指定。

<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>dev</activeProfile><activeProfile>prod</activeProfile></activeProfiles>...
</settings>

配置说明：

顶级元素 activeProfiles：包含一组 activeProfile 元素，用于声明激活的 Profile 列表。
一级子元素 activeProfile：每个 activeProfile 元素的值对应一个 Profile 的 id。这个 id 必须与 pom.xml 或 profile.xml 中定义的 Profile 的 id 相匹配。

PS（注意事项）：将 Profile 激活放在 settings.xml 中，可以确保在所有 Maven 构建中使用相同的 Profile，而不必在每个 POM 文件中显式指定。这对于需要一致性和统一配置的团队非常有用。