Maven插件【版本发布自动化】:maven-release-plugin

12/31/2025 后端开发构建工具Maven

目录


参考


# Maven插件【版本发布自动化】:maven-release-plugin

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-release-plugin</artifactId>
    <version>${maven-release-plugin.version}</version>
    <configuration>
        <autoVersionSubmodules>true</autoVersionSubmodules>
        <tagNameFormat>@{project.version}</tagNameFormat>
        <tagBase>${project.version}</tagBase>
    </configuration>
    <dependencies>
        <dependency>
            <groupId>org.apache.maven.scm</groupId>
            <artifactId>maven-scm-provider-jgit</artifactId>
            <version>1.9.5</version>
        </dependency>
    </dependencies>
</plugin>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

这是 Maven Release Plugin,一个用于 自动化 Maven 项目版本发布流程 的核心插件。它通过标准化操作(如版本号更新、SCM 标签管理、构建部署等)简化发布过程,减少人为错误。以下是详细解析:


# 一、插件作用

  1. 版本发布自动化
    • 将开发版(如 1.0.0-SNAPSHOT)升级为正式版(如 1.0.0),并生成 Git/SVN 标签。
    • 自动提交版本号变更到版本控制系统(SCM),并部署构件到 Maven 仓库。
  2. 多模块项目支持
    • 通过 autoVersionSubmodules 配置,统一管理父子模块的版本号,避免手动逐个修改。
  3. 流程标准化
    • 强制检查未提交代码、快照依赖等问题,确保发布版本稳定性。

# 二、配置解析(用户提供的配置示例)

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-release-plugin</artifactId>
    <version>${maven-release-plugin.version}</version>
    <configuration>
        <autoVersionSubmodules>true</autoVersionSubmodules>  <!-- 自动同步子模块版本号 -->
        <tagNameFormat>@{project.version}</tagNameFormat>     <!-- 标签命名规则 -->
        <tagBase>${project.version}</tagBase>                <!-- 标签存储路径(需结合SCM配置) -->
    </configuration>
    <dependencies>
        <dependency>
            <groupId>org.apache.maven.scm</groupId>
            <artifactId>maven-scm-provider-jgit</artifactId>  <!-- 指定Git作为SCM实现 -->
            <version>1.9.5</version>
        </dependency>
    </dependencies>
</plugin>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
  • 关键参数:
    • autoVersionSubmodules:多模块项目中自动同步版本号,无需手动输入。
    • tagNameFormat:标签名称模板,@{project.version} 会被替换为实际版本号(如 1.0.0)。
    • tagBase:标签存储的基准路径(需与 pom.xml 中的 <scm> 配置配合使用)。
    • SCM 依赖:显式指定 maven-scm-provider-jgit 以支持 Git 操作。

# 三、使用步骤

# 1. 前置条件

  • 确保 pom.xml 中已配置 <scm> 信息(Git 示例):

    <scm>
        <connection>scm:git:https://github.com/your-repo.git</connection>
        <developerConnection>scm:git:git@github.com:your-repo.git</developerConnection>
        <url>https://github.com/your-repo</url>
    </scm>
    
    1
    2
    3
    4
    5
  • 所有代码已提交,且无快照依赖(除非是项目自身版本)。

# 2. 执行发布流程

  • 准备阶段(检查与版本更新):

    mvn release:prepare
    
    1

    插件会交互式询问:

    • 发布版本号(默认基于当前 SNAPSHOT 去除后缀)。
    • 新开发版本号(如 1.0.1-SNAPSHOT)。
    • 自动创建标签(如 1.0.0)并提交到 SCM。
  • 执行阶段(构建与部署):

    mvn release:perform
    
    1

    从标签检出代码,执行 mvn deploy 部署到仓库。

  • 回滚(可选):

    mvn release:rollback  # 回退版本号变更(需手动删除标签)。
    
    1

# 3. 高级命令

  • 跳过交互:通过参数 -Darguments="-DskipTests" 跳过测试,或 -DdryRun=true 模拟运行。
  • 分支发布:使用 release:branch 创建发布分支。

# 四、注意事项

  1. 权限问题:确保 SCM 账号有创建标签/提交的权限。
  2. 网络稳定性:依赖 Maven 仓库和 SCM 服务的可用性。
  3. 多模块项目:建议启用 autoVersionSubmodules 保持版本一致。
  4. 插件版本:推荐使用最新稳定版(如 3.0.0+)以兼容 Java 11+。

# 五、典型问题解决

  • 错误:No SCM Provider configured 添加对应的 SCM 依赖(如 Git 需 maven-scm-provider-jgit)。
  • 错误:Cannot run program "svn" 安装 SVN 命令行工具或切换为 Git。

通过合理配置,该插件能显著提升发布效率和可靠性。完整文档参考 Apache 官方指南 (opens new window)


以下是:在多模块项目中,maven-release-plugin如何处理子模块的版本号?

在多模块项目中,maven-release-plugin 通过以下机制统一管理子模块的版本号,确保版本一致性和发布流程的自动化:


# 一、自动同步子模块版本号

  1. 父POM版本继承 子模块的 <parent> 标签中通常继承父POM的版本号(如 ${revision} 或显式版本)。当父POM版本更新时,插件会自动更新所有子模块的版本号,避免手动逐个修改。

    • 示例配置:

      <parent>
          <groupId>com.example</groupId>
          <artifactId>parent</artifactId>
          <version>${revision}</version> <!-- 动态版本变量 -->
      </parent>
      
      1
      2
      3
      4
      5
  2. autoVersionSubmodules 参数 在插件配置中启用此参数(默认 false),强制同步所有子模块版本:

    <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-release-plugin</artifactId>
        <version>3.0.0</version>
        <configuration>
            <autoVersionSubmodules>true</autoVersionSubmodules> <!-- 关键配置 -->
        </configuration>
    </plugin>
    
    1
    2
    3
    4
    5
    6
    7
    8
    • 作用:执行 release:prepare 时,插件会递归更新父子模块的版本号(如从 1.0-SNAPSHOT1.0)。

# 二、发布流程中的版本处理

  1. release:prepare 阶段
    • 交互式版本更新:插件会提示输入发布版本号(如 1.0)和新的开发版本号(如 1.1-SNAPSHOT),并自动修改所有相关POM文件。
    • SCM标签生成:根据 <tagNameFormat> 配置(如 v@{project.version})为所有模块生成统一标签(如 v1.0)。
  2. release:perform 阶段
    • 从标签检出代码后,插件会基于更新后的版本号构建和部署所有模块,确保发布的构件版本一致。

# 三、动态版本管理(${revision})

  1. 灵活版本控制 父POM中通过 ${revision} 变量统一管理版本号,插件在发布时自动替换为实际版本(如 1.0),无需手动修改子模块。

    • 配置示例:

      <properties>
          <revision>1.0-SNAPSHOT</revision>
      </properties>
      
      1
      2
      3
  2. flatten-maven-plugin 结合 使用 flatten-maven-plugin 解决 ${revision} 在部署时的解析问题,生成扁平化POM文件:

    <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>flatten-maven-plugin</artifactId>
        <version>1.3.0</version>
        <executions>
            <execution>
                <id>flatten</id>
                <phase>process-resources</phase>
                <goals><goal>flatten</goal></goals>
            </execution>
        </executions>
    </plugin>
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    • 作用:确保发布的POM文件中 ${revision} 被替换为实际值。

# 四、注意事项

  1. SCM配置必须完整 父POM和子模块均需正确配置 <scm> 信息,否则插件无法同步提交版本变更或生成标签。

    • 示例:

      <scm>
          <connection>scm:git:git@github.com:your-repo.git</connection>
          <developerConnection>scm:git:git@github.com:your-repo.git</developerConnection>
      </scm>
      
      1
      2
      3
      4
  2. 避免快照依赖 发布前需确保子模块间无快照依赖(如 1.0-SNAPSHOT),否则会中断流程。

  3. 复杂依赖项目的替代方案 对于模块间依赖复杂的项目,可考虑 cascading-release-maven-plugin,它能智能处理依赖顺序和版本升级。


# 五、总结

场景 插件行为 引用来源
版本号同步 通过 autoVersionSubmodules=true 自动更新父子模块版本
动态版本管理 替换 ${revision} 为实际版本号,结合 flatten-maven-plugin 确保部署兼容性
SCM标签生成 统一为所有模块生成标签(如 v1.0
错误处理 检测快照依赖或缺失SCM配置,中断发布流程

通过合理配置,maven-release-plugin 能高效管理多模块项目的版本发布,减少人工干预和错误风险。

上次更新时间: 8/3/2025, 10:09:53 AM