跳到主要内容

settings.xml 配置

settings.xml 是 Maven 的全局配置文件，用于配置适用于所有项目的设置，如本地仓库位置、镜像源、服务器认证信息等。与 pom.xml 不同，settings.xml 不应绑定到具体项目，而是配置构建环境本身。

配置文件位置​

Maven 的 settings.xml 可以放在两个位置：

位置说明路径
全局配置Maven 安装目录下${maven.home}/conf/settings.xml
用户配置用户主目录下${user.home}/.m2/settings.xml

全局配置对所有用户生效，用户配置只对当前用户生效。当两个文件同时存在时，Maven 会合并它们的配置，用户配置会覆盖全局配置中的相同元素。

建议在用户目录下创建用户级别的 settings.xml，这样升级 Maven 时不会丢失配置。

配置文件结构​

一个完整的 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 
                              https://maven.apache.org/xsd/settings-1.0.0.xsd">
    
    <!-- 本地仓库位置 -->
    <localRepository/>
    
    <!-- 交互模式 -->
    <interactiveMode/>
    
    <!-- 离线模式 -->
    <offline/>
    
    <!-- 插件组 -->
    <pluginGroups/>
    
    <!-- 服务器认证信息 -->
    <servers/>
    
    <!-- 镜像配置 -->
    <mirrors/>
    
    <!-- 代理配置 -->
    <proxies/>
    
    <!-- Profile 配置 -->
    <profiles/>
    
    <!-- 激活的 Profile -->
    <activeProfiles/>
    
</settings>

基本配置元素​

localRepository（本地仓库位置）​

指定 Maven 本地仓库的存储位置：

<settings>
    <!-- 默认为 ${user.home}/.m2/repository -->
    <localRepository>D:/maven/repository</localRepository>
</settings>

建议将本地仓库设置在非系统盘，避免占用系统盘空间。同时，路径中不要包含中文和空格。

interactiveMode（交互模式）​

控制 Maven 是否在需要时与用户交互：

<settings>
    <!-- 默认为 true -->
    <interactiveMode>true</interactiveMode>
</settings>

在自动化构建环境中，可以设置为 false 禁用交互。

offline（离线模式）​

设置 Maven 是否在离线模式下运行：

<settings>
    <!-- 默认为 false -->
    <offline>false</offline>
</settings>

离线模式下，Maven 不会尝试从远程仓库下载构件，只使用本地仓库中的内容。这在无法连接网络或需要严格控制构件来源时很有用。

pluginGroups（插件组）​

pluginGroups 定义了在命令行使用插件时的 groupId 搜索顺序。当执行 mvn plugin:goal 且没有指定插件的 groupId 时，Maven 会按顺序搜索这些 groupId。

<settings>
    <pluginGroups>
        <pluginGroup>org.eclipse.jetty</pluginGroup>
        <pluginGroup>org.codehaus.mojo</pluginGroup>
    </pluginGroups>
</settings>

默认已包含 org.apache.maven.plugins 和 org.codehaus.mojo。

配置后，可以使用简化命令：

# 完整命令
mvn org.eclipse.jetty:jetty-maven-plugin:run

# 简化命令
mvn jetty:run

servers（服务器认证）​

servers 配置用于存储访问远程仓库或私服的认证信息。这类敏感信息不应放在 pom.xml 中，而应放在 settings.xml 中。

<settings>
    <servers>
        <server>
            <!-- 服务器 ID，必须与 pom.xml 中 repository 的 id 匹配 -->
            <id>nexus-releases</id>
            <username>admin</username>
            <password>admin123</password>
        </server>
        
        <server>
            <id>nexus-snapshots</id>
            <username>admin</username>
            <password>admin123</password>
        </server>
        
        <!-- 使用私钥认证 -->
        <server>
            <id>ssh-server</id>
            <privateKey>${user.home}/.ssh/id_rsa</privateKey>
            <passphrase>my_passphrase</passphrase>
        </server>
    </servers>
</settings>

认证元素说明​

元素说明
id服务器标识，必须与 pom.xml 中 repository 的 id 一致
username用户名
password密码
privateKey私钥文件路径（SSH 认证）
passphrase私钥密码（如果私钥有密码）
filePermissions文件权限（部署时）
directoryPermissions目录权限（部署时）

密码加密​

Maven 支持对密码进行加密，避免明文存储敏感信息：

<server>
    <id>nexus</id>
    <username>admin</username>
    <!-- 加密后的密码 -->
    <password>{COQLCE6DU6GtcS5P=}</password>
</server>

创建加密密码的步骤：

# 1. 创建主密码
mvn --encrypt-master-password <master_password>

# 2. 将主密码保存到 ~/.m2/settings-security.xml
# 3. 加密服务器密码
mvn --encrypt-password <server_password>

mirrors（镜像配置）​

镜像用于拦截对远程仓库的请求，将其重定向到另一个地址。通常用于加速下载或使用企业内部私服。

<settings>
    <mirrors>
        <!-- 阿里云镜像 -->
        <mirror>
            <id>aliyun</id>
            <name>阿里云公共仓库</name>
            <url>https://maven.aliyun.com/repository/public</url>
            <mirrorOf>central</mirrorOf>
        </mirror>
        
        <!-- 镜像所有仓库到私服 -->
        <mirror>
            <id>nexus</id>
            <name>Nexus Mirror</name>
            <url>http://nexus.example.com/repository/maven-public/</url>
            <mirrorOf>*</mirrorOf>
        </mirror>
    </mirrors>
</settings>

mirrorOf 配置详解​

mirrorOf 指定镜像代理哪些仓库：

值说明
central只代理中央仓库
*代理所有仓库
external:*代理所有非本地仓库
repo1,repo2代理指定的多个仓库
*,!repo1代理除 repo1 外的所有仓库
external:*,!repo1代理除 repo1 外的所有外部仓库

常用镜像源​

<!-- 阿里云 -->
<mirror>
    <id>aliyun</id>
    <url>https://maven.aliyun.com/repository/public</url>
    <mirrorOf>central</mirrorOf>
</mirror>

<!-- 华为云 -->
<mirror>
    <id>huawei</id>
    <url>https://repo.huaweicloud.com/repository/maven/</url>
    <mirrorOf>central</mirrorOf>
</mirror>

<!-- 腾讯云 -->
<mirror>
    <id>tencent</id>
    <url>https://mirrors.cloud.tencent.com/nexus/repository/maven-public/</url>
    <mirrorOf>central</mirrorOf>
</mirror>

镜像配置注意事项​

  1. id 必须唯一：每个 mirror 的 id 必须唯一，如果需要配置认证，id 要与 server 的 id 对应
  2. mirrorOf 不能匹配自己的 id：这会导致循环引用
  3. 多个镜像时只有一个生效：当有多个镜像匹配同一个仓库时，只有第一个会生效
  4. 镜像会完全替代目标仓库：使用镜像后，原仓库的 URL 不会被访问

proxies（代理配置）​

在企业网络环境中，可能需要通过代理服务器访问外网。proxies 配置用于设置 HTTP 代理。

<settings>
    <proxies>
        <proxy>
            <id>my-proxy</id>
            <active>true</active>
            <protocol>http</protocol>
            <host>proxy.example.com</host>
            <port>8080</port>
            <username>proxyuser</username>
            <password>proxypass</password>
            <!-- 不使用代理的主机 -->
            <nonProxyHosts>localhost|127.0.0.1|*.internal.com</nonProxyHosts>
        </proxy>
    </proxies>
</settings>

代理元素说明​

元素说明
id代理标识，用于区分多个代理配置
active是否激活此代理，同一时间只能有一个代理激活
protocol代理协议，支持 http 和 https
host代理服务器地址
port代理服务器端口
username代理认证用户名（如需要）
password代理认证密码（如需要）
nonProxyHosts不使用代理的主机列表，用 `

profiles（Profile 配置）​

settings.xml 中的 profile 与 pom.xml 中的 profile 类似，但只包含以下元素：

  • activation（激活条件）
  • properties（属性）
  • repositories（仓库）
  • pluginRepositories（插件仓库）

基本结构​

<settings>
    <profiles>
        <profile>
            <id>my-profile</id>
            
            <!-- 激活条件 -->
            <activation>
                <activeByDefault>false</activeByDefault>
                <jdk>17</jdk>
            </activation>
            
            <!-- 属性定义 -->
            <properties>
                <db.url>jdbc:mysql://localhost:3306/dev_db</db.url>
            </properties>
            
            <!-- 仓库配置 -->
            <repositories>
                <repository>
                    <id>special-repo</id>
                    <url>https://repo.example.com/maven2</url>
                </repository>
            </repositories>
        </profile>
    </profiles>
</settings>

激活条件​

profile 可以通过多种方式激活：

<profile>
    <id>my-profile</id>
    <activation>
        <!-- 默认激活 -->
        <activeByDefault>true</activeByDefault>
        
        <!-- JDK 版本匹配 -->
        <jdk>17</jdk>
        <!-- 或使用范围 -->
        <jdk>[11,17)</jdk>
        
        <!-- 操作系统匹配 -->
        <os>
            <name>Windows 10</name>
            <family>Windows</family>
            <arch>amd64</arch>
        </os>
        
        <!-- 系统属性匹配 -->
        <property>
            <name>env</name>
            <value>dev</value>
        </property>
        
        <!-- 文件存在/不存在 -->
        <file>
            <exists>${project.basedir}/config.properties</exists>
            <missing>${project.basedir}/deploy.properties</missing>
        </file>
    </activation>
</profile>

仓库配置​

在 profile 中配置的仓库会添加到项目的仓库列表中：

<profile>
    <id>extra-repos</id>
    <repositories>
        <repository>
            <id>spring-milestone</id>
            <name>Spring Milestone Repository</name>
            <url>https://repo.spring.io/milestone</url>
            <releases>
                <enabled>true</enabled>
            </releases>
            <snapshots>
                <enabled>false</enabled>
            </snapshots>
        </repository>
    </repositories>
    
    <pluginRepositories>
        <pluginRepository>
            <id>spring-plugin</id>
            <url>https://repo.spring.io/milestone</url>
        </pluginRepository>
    </pluginRepositories>
</profile>

仓库更新策略​

<repository>
    <id>my-repo</id>
    <url>https://repo.example.com/maven2</url>
    <releases>
        <enabled>true</enabled>
        <!-- 更新策略：always, daily（默认）, interval:X（分钟）, never -->
        <updatePolicy>daily</updatePolicy>
        <!-- 校验和策略：ignore, warn, fail -->
        <checksumPolicy>warn</checksumPolicy>
    </releases>
    <snapshots>
        <enabled>true</enabled>
        <updatePolicy>always</updatePolicy>
        <checksumPolicy>fail</checksumPolicy>
    </snapshots>
</repository>

activeProfiles（激活的 Profile）​

activeProfiles 用于指定默认激活的 profile：

<settings>
    <activeProfiles>
        <activeProfile>my-profile</activeProfile>
        <activeProfile>extra-repos</activeProfile>
    </activeProfiles>
</settings>

这些 profile 会自动激活，无论其 activation 条件如何。

属性引用​

settings.xml 中可以使用以下属性：

<settings>
    <!-- 环境变量 -->
    <localRepository>${env.M2_REPO}/repository</localRepository>
    
    <!-- 系统属性 -->
    <localRepository>${user.home}/.m2/repository</localRepository>
    
    <!-- 在 profile 中定义的属性 -->
    <profiles>
        <profile>
            <id>my-profile</id>
            <properties>
                <custom.path>/opt/app</custom.path>
            </properties>
        </profile>
    </profiles>
</settings>

注意：settings.xml 中定义的属性不能用于 settings.xml 自身的插值，只能在 POM 中引用。

完整配置示例​

以下是一个完整的 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 
                              https://maven.apache.org/xsd/settings-1.0.0.xsd">
    
    <!-- 本地仓库位置 -->
    <localRepository>D:/maven/repository</localRepository>
    
    <!-- 交互模式 -->
    <interactiveMode>true</interactiveMode>
    
    <!-- 离线模式 -->
    <offline>false</offline>
    
    <!-- 插件组 -->
    <pluginGroups>
        <pluginGroup>org.eclipse.jetty</pluginGroup>
    </pluginGroups>
    
    <!-- 服务器认证 -->
    <servers>
        <server>
            <id>nexus-releases</id>
            <username>admin</username>
            <password>{encrypted_password}</password>
        </server>
        <server>
            <id>nexus-snapshots</id>
            <username>admin</username>
            <password>{encrypted_password}</password>
        </server>
    </servers>
    
    <!-- 镜像配置 -->
    <mirrors>
        <mirror>
            <id>aliyun</id>
            <name>阿里云公共仓库</name>
            <url>https://maven.aliyun.com/repository/public</url>
            <mirrorOf>central</mirrorOf>
        </mirror>
    </mirrors>
    
    <!-- Profile 配置 -->
    <profiles>
        <!-- JDK 17 配置 -->
        <profile>
            <id>jdk-17</id>
            <activation>
                <jdk>17</jdk>
            </activation>
            <properties>
                <maven.compiler.source>17</maven.compiler.source>
                <maven.compiler.target>17</maven.compiler.target>
            </properties>
        </profile>
        
        <!-- 开发环境 -->
        <profile>
            <id>dev</id>
            <properties>
                <env>dev</env>
            </properties>
            <repositories>
                <repository>
                    <id>nexus</id>
                    <url>http://nexus.example.com/repository/maven-public/</url>
                </repository>
            </repositories>
        </profile>
        
        <!-- 生产环境 -->
        <profile>
            <id>prod</id>
            <properties>
                <env>prod</env>
            </properties>
        </profile>
    </profiles>
    
    <!-- 默认激活的 Profile -->
    <activeProfiles>
        <activeProfile>dev</activeProfile>
    </activeProfiles>
    
</settings>

常用命令​

查看有效配置：

# 查看有效 settings
mvn help:effective-settings

# 查看激活的 profile
mvn help:active-profiles

# 查看所有 profile
mvn help:all-profiles

配置最佳实践​

1. 使用用户级配置​

推荐使用用户级 settings.xml（~/.m2/settings.xml），而不是修改全局配置。这样升级 Maven 时不会丢失配置。

2. 加密敏感信息​

对于密码等敏感信息，使用 Maven 的密码加密功能，避免明文存储。

3. 合理配置镜像​

  • 开发环境：配置国内镜像加速下载
  • 企业环境：配置企业私服作为镜像

4. 仓库配置统一管理​

在企业环境中，将仓库配置放在 settings.xml 的 profile 中，而不是每个项目的 pom.xml。

5. 使用环境变量​

对于可能变化的配置（如私服地址），使用环境变量：

<server>
    <id>nexus</id>
    <username>${env.NEXUS_USER}</username>
    <password>${env.NEXUS_PASSWORD}</password>
</server>

6. 分离开发和生产配置​

使用不同的 profile 管理不同环境的配置，避免误操作。

小结​

本章详细讲解了 Maven settings.xml 的配置：

  1. settings.xml 的位置和优先级
  2. 基本配置元素（localRepository、interactiveMode、offline）
  3. 服务器认证配置
  4. 镜像配置详解
  5. 代理配置
  6. Profile 配置和激活
  7. 完整配置示例
  8. 配置最佳实践

settings.xml 是 Maven 环境配置的核心，合理配置可以显著提升构建效率和管理便利性。