一、起源

  • 开发阶段的构件需要频繁覆盖更新,正式发布的构件必须保持不可变,否则依赖方的构建结果无法复现。
  • 手工修改版本号在多模块工程中容易遗漏,发布前的版本替换、打标签、推送、还原开发版本等步骤繁琐且易错。
  • 版本管理与发布流程的目标,是把"开发期可变"与"发布后不可变"两种状态分开管理,并把重复步骤自动化。

二、原理

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 包,签名不完整 补充打包插件与签名配置,重新执行发布

五、总结

  1. SNAPSHOT 用于开发期覆盖更新,Release 用于对外发布且不可覆盖。
  2. 发布前必须确认版本号、依赖树与认证配置,三者任一缺失都会导致发布失败或结果不可复现。
  3. versions:set 适合统一版本,release 插件适合需要标签与留痕的正式发布。
  4. 中央仓库发布额外要求签名、源码包与 Javadoc 包,凭证通过 CI 注入而非写入配置文件。