一、起源
- POM 随代码提交到仓库,凡是与机器、账号、网络环境相关的内容都不能写进 POM,否则不同环境的构建行为互相干扰。
- 这一类配置需要集中存放在构建工具自身的配置文件中,于是形成 settings.xml:描述"在这台机器上如何访问仓库",而 POM 描述"这个项目需要什么构件"。
- 两者混用的典型后果:私服密码被提交到 Git,或者镜像配置写进 POM 后导致其他环境下载失败。
二、原理
2.1 三层来源与优先级
| 层级 | 位置 | 说明 |
| 全局配置 | ${maven.home}/conf/settings.xml | 整台机器共享,通常由安装时提供 |
| 用户配置 | ${user.home}/.m2/settings.xml | 当前用户私有,优先级高于全局配置 |
| 命令行指定 | -s 用户配置、-gs 全局配置 | 用于临时切换或 CI 中指定专用配置 |
- 合并规则:用户级配置覆盖全局配置中的同项设置;
mirrors、servers、profiles 按 id 合并,同名项以用户级为准。
- profile 是否生效取决于激活条件,未激活的 profile 不参与合并。
- 最终生效结果可用
mvn help:effective-settings 输出,排查配置问题应以该结果为准,而不是只看文件内容。
2.2 与 POM 的职责边界
| 配置项 | 应写在 settings.xml | 应写在 POM |
| 本地仓库路径 | 是 | 否 |
| 镜像(替换仓库地址) | 是 | 否 |
| 仓库账号与密码 | 是 | 否 |
| 私有仓库地址 | 视情况,通常 POM 中声明仓库、settings 中配置镜像与认证 | 是 |
| 构件发布目标仓库 | 否 | 是,distributionManagement |
| 依赖与插件版本 | 否 | 是 |
| 环境相关属性 | 是,profile 中定义 | 可定义默认值 |
2.3 认证的匹配方式
settings.xml 中的 <server> 以 <id> 与 POM 中的 <repository> 或 <distributionManagement> 的 <id> 匹配。
- 匹配只认
id,与仓库 URL 无关。两处 id 不一致时,即使账号密码正确也会返回 401。
- 密码可加密存储,避免配置文件被复制后泄露明文。
三、实现
3.1 文件位置与验证
# 查看合并后实际生效的 settings
mvn help:effective-settings
# 使用指定配置文件构建
mvn -s /path/to/settings.xml clean package
- 修改 settings.xml 后不需要重启终端,但 IDE 需要重新加载 Maven 项目才能生效。
3.2 本地仓库路径
<localRepository>D:/maven-repo</localRepository>
- 默认值为
${user.home}/.m2/repository。
- 迁移本地仓库后,旧目录中的构件不会自动复制,首次构建会重新下载。
- 多个 Maven 安装共用同一本地仓库时,不建议同时执行构建写操作。
3.3 镜像与 mirrorOf 语义
<mirrors>
<mirror>
<id>aliyun</id>
<name>Aliyun Public Mirror</name>
<url>https://maven.aliyun.com/repository/public</url>
<mirrorOf>central</mirrorOf>
</mirror>
</mirrors>
mirrorOf 决定哪些仓库请求会被重定向到该镜像:
| 取值 | 含义 |
central | 只镜像中央仓库 |
* | 镜像所有仓库,包括私服 |
external:* | 镜像所有非本机、非文件协议的仓库 |
repo1,repo2 | 只镜像指定 id 的仓库 |
*,!repo1 | 镜像除 repo1 外的所有仓库 |
mirrorOf 写 * 会把私服请求一并重定向到公网镜像,导致内部构件无法下载。存在私服时应使用 external:* 或显式排除私服 id。
- 同一个仓库只能被一个镜像匹配,多个镜像同时匹配时以先声明者为准。
3.4 仓库认证
<servers>
<server>
<id>nexus-releases</id>
<username>deployer</username>
<password>{加密后的密码}</password>
</server>
</servers>
<id> 必须与 POM 中 <repository> 或 <distributionManagement> 的 <id> 完全一致。
- 密码加密:
mvn --encrypt-master-password
mvn --encrypt-password
- 加密后的密码依赖
~/.m2/settings-security.xml 中的主密码,迁移机器时两个文件需要一起迁移。
- CI 环境通常通过环境变量或密钥管理注入,避免将加密配置写入镜像。
3.5 profiles
<profiles>
<profile>
<id>dev</id>
<activation>
<activeByDefault>true</activeByDefault>
</activation>
<properties>
<db.url>jdbc:mysql://127.0.0.1:3306/demo</db.url>
</properties>
<repositories>
<repository>
<id>nexus-snapshots</id>
<url>http://nexus.example.com/repository/snapshots/</url>
<snapshots><enabled>true</enabled></snapshots>
<releases><enabled>false</enabled></releases>
</repository>
</repositories>
</profile>
</profiles>
- settings 中的 profile 可包含
<properties>、<repositories>、<pluginRepositories>,不能包含 <build> 中的插件配置与 distributionManagement,这两类只能在 POM 中定义。
- 激活方式包括
activeByDefault、-P 指定、按属性、按 JDK 版本、按操作系统。
- 多个 profile 同时激活且定义同名属性时,实际取值受激活与声明顺序影响,应避免同名属性分散在多个 profile 中。
3.6 pluginGroups
<pluginGroups>
<pluginGroup>com.example.maven.plugins</pluginGroup>
</pluginGroups>
- 命令行调用插件时如果省略
groupId,Maven 默认只会在 org.apache.maven.plugins 与 org.codehaus.mojo 中查找。
- 公司内部插件需要加入
pluginGroups 才能省略 groupId 调用,否则必须写全坐标。
3.7 离线与交互模式
<offline>false</offline>
offline=true 等价于命令行 -o,所有构件只能从本地仓库解析,缺失即失败。
- 离线模式适用于网络受限环境,使用前需确认本地仓库已完整。
3.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-repo</localRepository>
<mirrors>
<mirror>
<id>aliyun</id>
<url>https://maven.aliyun.com/repository/public</url>
<mirrorOf>external:*,!nexus-releases,!nexus-snapshots</mirrorOf>
</mirror>
</mirrors>
<servers>
<server>
<id>nexus-releases</id>
<username>deployer</username>
<password>{加密后的密码}</password>
</server>
</servers>
</settings>
- 该配置的作用是:公网构件走镜像,私服请求按排除规则保留原地址,发布认证按
id 匹配。
四、常见错误
| 现象 | 常见原因 | 处理方式 |
| 401 Unauthorized | server 的 id 与仓库 id 不一致,或密码加密后主密码文件缺失 | 对齐 id;确认 settings-security.xml 存在 |
| 私服构件下载不到 | mirrorOf 写 *,把私服请求重定向到公网镜像 | 改为 external:* 或显式排除私服 id |
| 镜像配置未生效 | 修改的是全局配置而用户配置覆盖了该项,或 IDE 未重新加载 | 用 help:effective-settings 确认生效结果,重新加载 IDE |
| 本地仓库路径不生效 | settings 中有多处 localRepository,或命令行 -Dmaven.repo.local 覆盖 | 统一配置来源,检查启动脚本参数 |
| settings.xml 解析失败 | 编码不是 UTF-8,或 XML 标签未闭合 | 统一 UTF-8 编码并校验 XML |
| 密码明文泄露 | 直接将密码写入 settings.xml 并同步到共享目录 | 使用加密密码或 CI 注入 |
五、总结
- settings.xml 描述机器与用户的仓库访问方式,POM 描述项目自身需求,两者不应混用。
- 用户配置优先于全局配置,实际生效结果以
help:effective-settings 为准。
mirrorOf 决定请求重定向范围,存在私服时避免使用 *。
- 认证只按
id 匹配,密码应加密或由 CI 注入,不写入版本库。