构建与依赖 / 系统课时
deploy 与远程仓库发布
deploy 与远程仓库发布
mvn deploy 用于把项目制品发布到团队可访问的远程 Maven 仓库。一个可用的发布配置需要同时完成两件事:POM 中声明 release 与 snapshot 的发布地址,用户或 CI 的 settings.xml 中用相同的服务器 id 提供认证信息。
学习目标
- 能用
distributionManagement为 release 与 snapshot 指定不同的远程仓库。 - 能用
settings.xml的server.id与发布仓库建立认证绑定,而不把密钥提交进 POM。 - 能执行
mvn deploy,并按 401、403、仓库策略不匹配等现象定位失败位置。
用 distributionManagement 指定发布目标
distributionManagement 描述“构建完成后发布到哪里”,它不是普通依赖下载仓库配置。真实项目通常把正式版和 SNAPSHOT 分开存放。下面是项目 pom.xml 的片段示例,URL 需替换为仓库管理员提供的部署端点:
<distributionManagement>
<repository>
<id>company-releases</id>
<url>https://repo.company.example/repository/maven-releases/</url>
</repository>
<snapshotRepository>
<id>company-snapshots</id>
<url>https://repo.company.example/repository/maven-snapshots/</url>
</snapshotRepository>
</distributionManagement>版本 1.0.0 会走 release 仓库,1.1.0-SNAPSHOT 会走 snapshot 仓库。发布链路中至少有项目坐标、仓库选择和认证三组信息需要同时对应,适合用一张图核对。

如果父 POM 已统一声明 distributionManagement,子模块通常无需重复配置;先检查继承结果,再决定是否在当前模块新增。
用 server id 绑定认证
账号和令牌不应写进项目 POM。Maven 会用 distributionManagement 中的仓库 id 去匹配 settings.xml 里的 <server><id>。下面给出一个完整的最小 settings.xml,通过环境变量注入用户名和令牌:
<settings>
<servers>
<server>
<id>company-releases</id>
<username>${env.MAVEN_REPO_USER}</username>
<password>${env.MAVEN_REPO_TOKEN}</password>
</server>
<server>
<id>company-snapshots</id>
<username>${env.MAVEN_REPO_USER}</username>
<password>${env.MAVEN_REPO_TOKEN}</password>
</server>
</servers>
</settings>验证时最重要的不是用户名长什么样,而是两个 id 是否逐字一致。例如 POM 写 company-releases、settings 写 company-release,Maven 就不会把那组凭据用于该仓库。
执行 deploy 并验证发布
配置完成后,在项目根目录执行。deploy 位于默认生命周期后段,因此前面的测试、打包和本地安装也会先执行;任何前置阶段失败,远程发布都不会发生。
mvn -s <PATH>/settings.xml clean deploy预期输出的关键结果:
[INFO] BUILD SUCCESS成功后,以 com.example:pricing-core:1.0.0 为例,release 仓库中应能按 Maven 布局找到 com/example/pricing-core/1.0.0/,其中至少包含项目 POM 和主制品。若发布的是 1.1.0-SNAPSHOT,远程仓库通常还会维护 SNAPSHOT 元数据和时间戳化文件名,因此不要用“远端文件名必须等于本地 SNAPSHOT JAR 名”作为唯一验收条件。
需要确认当前项目最终使用了哪份发布配置时,可生成 effective POM:
mvn help:effective-pom -Doutput=<PATH>/effective-pom.xml预期输出的关键结果:
[INFO] Effective-POM written to: <PATH>/effective-pom.xml
[INFO] BUILD SUCCESS打开该文件搜索 distributionManagement,即可判断发布地址来自当前 POM 还是父 POM。该文件适合排查继承关系,但不应作为项目源码提交。
按状态码定位失败
远程发布失败时不要先改插件版本,按“地址 → id → 凭据 → 权限 → 仓库策略”的顺序检查更快。常见现象可以这样处理:
| 现象 | 优先检查 | 典型修复 |
|---|---|---|
| HTTP 401 | server.id 是否匹配、用户名或令牌是否有效 |
修正 id,重新注入有效凭据 |
| HTTP 403 | 账号已认证但没有部署权限 | 给部署账号写权限,或改用允许写入的 hosted 仓库 |
| 连接失败或 404 | distributionManagement.url 是否是部署端点 |
使用仓库管理员提供的 Maven 仓库 URL,不要填网页浏览地址 |
| release 被拒绝 | 版本已存在或仓库禁止覆盖正式版 | 提升版本号,不要覆盖已发布 release |
| SNAPSHOT 被拒绝 | 发布到了只接收 release 的仓库 | 检查版本后缀与 snapshotRepository URL |
很多仓库管理器会禁止覆盖正式版本,这正是制品可追溯性的基础。发布 1.0.0 后如果还要修复内容,应改成新的版本号;开发中的频繁迭代则使用 -SNAPSHOT,待验证完成后再生成新的 release 版本。