Maven settings.xml 与仓库配置全面详解

settings.xml 是 Maven 的用户级/全局级配置，独立于项目 POM。它控制本地仓库位置、远程仓库与镜像、认证凭据、Profile 激活等。配置错误是"依赖下载失败""认证不通过"的高频原因。

仓库体系

Maven 仓库
├── 本地仓库（Local）           ~/.m2/repository/
├── 中央仓库（Central）          https://repo.maven.apache.org/maven2/
└── 远程仓库（Remote）           Nexus / Artifactory / 镜像站

依赖查找顺序：本地仓库 → 远程仓库（含镜像）→ 下载失败则报错。

本地仓库

默认路径 ${user.home}/.m2/repository，可修改：

xml

<settings>
    <localRepository>D:/maven-repo</localRepository>
</settings>

本地仓库是构建的缓存层：依赖先落本地，二次构建不再下载。mvn install 就是把构件放入本地仓库。

中央仓库与私有仓库

中央仓库：官方全局仓库，所有坐标的默认来源
私有仓库（Nexus/Artifactory）：企业内部统一存储与分发，通常作为中央仓库的代理（mirror）

xml

<!-- pom.xml 中声明私有仓库（项目级） -->
<repositories>
    <repository>
        <id>nexus</id>
        <url>https://nexus.example.com/repository/maven-public/</url>
        <releases><enabled>true</enabled></releases>
        <snapshots><enabled>true</enabled></snapshots>
    </repository>
</repositories>

<!-- 私有仓库上的插件仓库（插件也要下载） -->
<pluginRepositories>
    <pluginRepository>
        <id>nexus</id>
        <url>https://nexus.example.com/repository/maven-public/</url>
    </pluginRepository>
</pluginRepositories>

镜像（Mirror）配置

镜像用于把某个仓库的请求转发到另一个地址，最常见用途：中央仓库 → 阿里云镜像。

xml

<mirrors>
    <mirror>
        <id>aliyunmaven</id>
        <mirrorOf>central</mirrorOf>
        <name>阿里云公共仓库</name>
        <url>https://maven.aliyun.com/repository/public</url>
    </mirror>
</mirrors>

mirrorOf 取值

mirrorOf 值	含义
`central`	仅镜像中央仓库
`*`	镜像所有远程仓库（最常用，接管全部下载）
`external:*`	镜像除本地外的所有外部仓库
`repo1,repo2`	镜像指定 id 的仓库
`*,!nexus`	镜像所有仓库但排除 nexus

使用 * 镜像所有仓库后，POM 中声明的私有仓库请求也会被转发到镜像地址，通常配合私有仓库统一走 Nexus 代理。

服务器认证（Server）

远程仓库需要认证时（deploy 发布、私有仓库拉取），在 <servers> 中配置凭据，id 必须与仓库的 id 一致：

xml

<servers>
    <server>
        <id>nexus-releases</id>
        <username>deploy-user</username>
        <password>deploy-password</password>
    </server>
</servers>

认证信息用于 mvn deploy 上传，以及需要鉴权的私有仓库下载。

密码加密

明文密码存在 settings.xml 有安全风险，可用 mvn -emp 加密：

bash

mvn -emp master-password     # 生成主密码
mvn -ep deploy-password      # 用主密码加密业务密码

settings.xml 中使用 ${settings.security.master} 与加密后的值。

settings.xml 层级与优先级

层级	位置	作用域	优先级
全局	`MAVEN_HOME/conf/settings.xml`	所有用户	低
用户	`${user.home}/.m2/settings.xml`	当前用户	高

相同配置项（如 localRepository、mirrors）用户级覆盖全局级。团队开发建议：

全局：基础配置（本地仓库路径、公共镜像）
用户：个人覆盖（私服认证、个人镜像）

Profile 与 settings 中的激活

settings.xml 中也可以定义 <profiles>，配合 <activeProfiles> 永久激活：

xml

<settings>
    <profiles>
        <profile>
            <id>default-jdk</id>
            <activation>
                <activeByDefault>true</activeByDefault>
            </activation>
            <properties>
                <maven.compiler.source>21</maven.compiler.source>
                <maven.compiler.target>21</maven.compiler.target>
            </properties>
        </profile>
    </profiles>
    <activeProfiles>
        <activeProfile>default-jdk</activeProfile>
    </activeProfiles>
</settings>

settings 中的 Profile 属性对所有项目生效，常用于统一 JDK 编译版本、统一仓库配置。

常用配置项总览

配置项	说明
`<localRepository>`	本地仓库路径
`<offline>`	是否离线模式（true/false）
`<mirrors>`	镜像配置
`<servers>`	服务器认证
`<proxies>`	代理（公司网络出口）
`<profiles>`	全局 Profile
`<activeProfiles>`	永久激活的 Profile
`<pluginGroups>`	插件前缀对应的 groupId（如 org.apache.maven.plugins）

常见问题

依赖下载 401/403？ 私有仓库需要认证，检查 <servers> 中 id 是否与仓库 id 一致、凭据是否正确。
下载失败但浏览器能访问？ 公司网络需要代理，配置 <proxies>；或镜像地址不通，换镜像。
settings.xml 改了不生效？ 检查是否改的是用户级文件（~/.m2/settings.xml），并确认无语法错误（mvn help:effective-settings 验证）。
本地仓库占用过大？ 手动清理 ~/.m2/repository 下的旧版本目录，或使用 mvn dependency:purge-local-repository 清理指定依赖。
私服与镜像的关系？ 常见架构：mirrorOf=* 指向 Nexus，Nexus 内部代理中央仓库与阿里云，实现全公司统一缓存与权限控制。

Maven settings.xml 与仓库配置全面详解 ​

仓库体系 ​

本地仓库 ​

中央仓库与私有仓库 ​

镜像（Mirror）配置 ​

mirrorOf 取值 ​

服务器认证（Server） ​

密码加密 ​

settings.xml 层级与优先级 ​

Profile 与 settings 中的激活 ​

常用配置项总览 ​

常见问题 ​