一、起源

  • 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 注入

五、总结

  1. settings.xml 描述机器与用户的仓库访问方式,POM 描述项目自身需求,两者不应混用。
  2. 用户配置优先于全局配置,实际生效结果以 help:effective-settings 为准。
  3. mirrorOf 决定请求重定向范围,存在私服时避免使用 *。
  4. 认证只按 id 匹配,密码应加密或由 CI 注入,不写入版本库。