一、起源
- 开发阶段的构件需要频繁覆盖更新,正式发布的构件必须保持不可变,否则依赖方的构建结果无法复现。
- 手工修改版本号在多模块工程中容易遗漏,发布前的版本替换、打标签、推送、还原开发版本等步骤繁琐且易错。
- 版本管理与发布流程的目标,是把"开发期可变"与"发布后不可变"两种状态分开管理,并把重复步骤自动化。
二、原理
2.1 SNAPSHOT 与 Release
| 维度 | SNAPSHOT | Release |
| 版本命名 | 1.0.0-SNAPSHOT | 1.0.0 |
| 可变性 | 可重复部署覆盖 | 发布后不应覆盖 |
| 远程存放 | 快照仓库 | 发布仓库 |
| 本地缓存检查 | 受 updatePolicy 与 -U 影响 | 已下载即复用,不再检查 |
| 使用范围 | 联调、内部集成 | 生产、对外提供 |
- 快照构件在远程仓库中可能带有时间戳,同一版本号对应多个实际文件,因此同一
-SNAPSHOT 在不同机器上可能解析到不同内容。
- Release 构件不可变,这是依赖可复现的前提。
2.2 发布需要的配置
- POM 中声明
distributionManagement,指定发布仓库与快照仓库地址。
settings.xml 中配置与仓库 id 一致的 server 认证信息。
- 私有仓库可能要求 GPG 签名、源码包与文档包,具体以仓库管理端规则为准。
- 发布前确认依赖树中不存在 SNAPSHOT 依赖。
2.3 两种发布方式
| 方式 | 过程 | 适用场景 |
手动 deploy | 手动改版本、提交、打标签、执行 mvn deploy | 流程简单、发布频率低 |
| release 插件 | release:prepare 自动改版本与打标签,release:perform 执行发布 | 多模块、需要严格留痕 |
三、实现
3.1 使用 versions 插件统一版本
# 统一修改所有模块的版本号
mvn versions:set -DnewVersion=1.1.0
# 确认修改(删除备份文件)
mvn versions:commit
# 撤销修改
mvn versions:revert
# 查看可升级的依赖版本
mvn versions:display-dependency-updates
versions:set 会为每个 POM 生成备份文件,未执行 commit 时备份仍存在,后续构建可能读到旧文件。
- 多模块工程的父子版本需要同时修改,插件默认处理全部模块,使用
-pl 限定范围时要确认父 POM 的版本引用是否同步更新。
- 依赖升级的验证要点见 Maven 依赖管理机制。
3.2 手动发布
# 确认版本已改为正式版,且无 SNAPSHOT 依赖
mvn -B clean deploy -DskipTests
3.3 release 插件流程
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-release-plugin</artifactId>
<version>3.0.1</version>
<configuration>
<tagNameFormat>v@{project.version}</tagNameFormat>
<pushChanges>false</pushChanges>
</configuration>
</plugin>
# 准备发布:改版本、提交、打标签、验证构建
mvn release:prepare
# 执行发布:检出标签版本并 deploy
mvn release:perform
- 使用前提:POM 中配置
<scm>,且工作区没有未提交的改动。
release:prepare 会依次确认发布版本、标签名与下一个开发版本号,也可通过 -DreleaseVersion、-DdevelopmentVersion、-Dtag 预先指定。
pushChanges 为 false 时只生成本地提交与标签,适合需要人工审核后再推送的流程。
- 流水线中执行时加
-B,避免交互等待导致任务挂起。
3.4 中央仓库发布要求
- 构件必须经过 GPG 签名,仓库会校验签名与公钥。
- 必须同时提供源码包与 Javadoc 包,否则校验不通过。
- 坐标中的
groupId 需要与组织验证过的命名空间一致,否则无法通过审核。
- 发布流程通常通过仓库管理端的收尾与发布动作完成,具体界面与步骤以所用仓库为准。
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-gpg-plugin</artifactId>
<version>3.1.0</version>
<executions>
<execution>
<id>sign-artifacts</id>
<phase>verify</phase>
<goals><goal>sign</goal></goals>
</execution>
</executions>
</plugin>
- 签名密码通过环境变量或
settings.xml 中的 gpg.passphrase 提供,不写入 POM。
- 发布机器需要导入签名私钥,CI 中通常以密钥文件挂载并限制权限。
3.5 CI 发布要点
- 凭证通过密钥管理注入,不写入日志;
settings.xml 可由流水线模板生成。
- 发布任务与日常构建任务分离,发布任务使用正式版本号,日常构建使用 SNAPSHOT。
- 发布前执行
mvn clean verify,避免跳过测试直接 deploy。
- 发布成功后生成标签与变更说明,便于回溯构件来源。
四、常见问题
| 现象 | 常见原因 | 处理方式 |
| 依赖方仍解析到旧代码 | 发布物仍是 SNAPSHOT,或本地仓库缓存了旧快照 | 使用正式版本;构建时加 -U 刷新快照 |
| 仓库拒绝覆盖构件 | 正式版本已存在 | 升级版本号后重新发布 |
release:prepare 中断 | 工作区有未提交改动,或版本号不符合规则 | 清理工作区,确认版本号格式 |
| 发布后本地仍是旧版本 | 未执行 versions:commit,或本地仓库未刷新 | 执行 commit 并清空对应坐标目录 |
| GPG 签名失败 | 私钥未导入,或密码未传入 | 导入私钥,通过环境变量提供密码 |
| 中央仓库校验不通过 | 缺少源码包或 Javadoc 包,签名不完整 | 补充打包插件与签名配置,重新执行发布 |
五、总结
- SNAPSHOT 用于开发期覆盖更新,Release 用于对外发布且不可覆盖。
- 发布前必须确认版本号、依赖树与认证配置,三者任一缺失都会导致发布失败或结果不可复现。
versions:set 适合统一版本,release 插件适合需要标签与留痕的正式发布。
- 中央仓库发布额外要求签名、源码包与 Javadoc 包,凭证通过 CI 注入而非写入配置文件。