构建与依赖 / 系统课时
settings.xml 配置文件
settings.xml 配置文件
settings.xml 用来保存只属于本机或构建环境的 Maven 配置,例如本地仓库目录、私服凭据和需要主动启用的 Profile。掌握全局与用户配置的覆盖关系后,就能把环境差异从项目 pom.xml 中移开,并用 Effective Settings 验证 Maven 最终真正读取了什么。
学习目标
- 区分全局与用户
settings.xml的位置和优先级。 - 配置
localRepository、servers与活动 Profile。 - 用 Maven 命令生成 Effective Settings,确认配置已经生效。
先确认 Maven 实际读取哪些 settings
Maven 常用两层配置:安装目录下的全局 ${maven.home}/conf/settings.xml,以及当前用户的 ${user.home}/.m2/settings.xml。团队统一的代理或基础策略可以放全局层,个人凭据和本机目录更适合放用户层;两层都存在时,用户配置会参与覆盖同 ID 的全局配置。
先执行下面命令确认当前 Maven 安装与 Java 环境,避免修改了另一套 Maven 的配置文件。
mvn -version预期输出中的版本、路径会因机器不同而变化,但结构类似:
Apache Maven <VERSION>
Maven home: <PATH>
Java version: <VERSION>, vendor: <VENDOR>, runtime: <PATH>
Default locale: <LOCALE>, platform encoding: <ENCODING>
OS name: "<OS>", version: "<VERSION>", arch: "<ARCH>", family: "<FAMILY>"
配置本地仓库、认证与活动 Profile
下面是一份可直接放到用户 ${user.home}/.m2/settings.xml 的完整示例。localRepository 改到独立目录;servers.server.id 必须与目标仓库的 ID 一致;账号密码从环境变量读取,避免把凭据写进项目仓库。
<?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>${user.home}/.m2/repository-work</localRepository>
<servers>
<server>
<id>corp-releases</id>
<username>${env.REPO_USER}</username>
<password>${env.REPO_PASSWORD}</password>
</server>
</servers>
<profiles>
<profile>
<id>corp-repo</id>
<repositories>
<repository>
<id>corp-releases</id>
<url>https://repo.example.com/repository/releases/</url>
<releases>
<enabled>true</enabled>
</releases>
<snapshots>
<enabled>false</enabled>
</snapshots>
</repository>
</repositories>
</profile>
</profiles>
<activeProfiles>
<activeProfile>corp-repo</activeProfile>
</activeProfiles>
</settings>这份配置生效后,依赖会缓存到 ${user.home}/.m2/repository-work;访问 corp-releases 时,Maven 会用同 ID 的 server 认证;corp-repo 因出现在 activeProfiles 中而自动启用。若仓库既提供 Release 又提供 Snapshot,应按仓库策略分别设置 releases 与 snapshots,不要默认全部开启。
生成 Effective Settings 做验收
不要只检查 XML 是否能打开,还要让 Maven 合并全局与用户配置。下面命令适用于 Bash、zsh、WSL 或 Git Bash:先生成 Effective Settings,再确认本地仓库、活动 Profile 和服务器 ID 都已进入最终配置。
mvn -q help:effective-settings -Doutput=effective-settings.xml && grep -Fq '<activeProfile>corp-repo</activeProfile>' effective-settings.xml && grep -Fq '<id>corp-releases</id>' effective-settings.xml && printf 'settings loaded\n'预期输出:
settings loaded生成的 effective-settings.xml 只用于检查,通常不提交版本库。验收时再搜索 <localRepository>,确认值已经解析为期望目录;如果命令没有输出 settings loaded,按顺序检查用户配置文件路径、XML 是否闭合、Profile ID 是否拼错,以及是否误用了另一套 Maven 安装。
避免三个常见配置错误
第一类错误是把私服用户名和密码写进 pom.xml。仓库地址可以属于项目,但凭据应放 settings.xml 的 servers 中,并让 server.id 与仓库或镜像 ID 对上。第二类错误是改了全局配置却忽略用户层同 ID 配置;出现“明明改了却没生效”时,应优先看 Effective Settings,而不是继续改 XML。
第三类错误是把 Profile 当成认证开关。Profile 负责激活属性、仓库等环境配置,认证仍由 servers 提供。若 corp-repo 已激活但访问私服仍返回 401,应先核对 server.id、环境变量 REPO_USER 与 REPO_PASSWORD,而不是反复切换 Profile。