Maven多模块项目含Git子模块：release:prepare执行失败求助

问题场景 #

现有Maven多模块项目结构如下：

proj-root
- proj-module
- proj-submodule（Git子模块）

执行mvn release:prepare时遭遇两次失败：

1. 首次因子模块处于分离HEAD状态，导致插件无法检测当前分支
2. 切换子模块到指定分支后，推送被拒绝，且子模块pom未同步更新版本

核心原因分析 #

1. 首次失败：git submodule update --init --remote默认会拉取子模块的指定commit而非分支，导致子模块进入分离HEAD状态，Maven release插件无法识别分支进行版本提交
2. 第二次失败：手动切换子模块分支后，根项目Git仓库中记录的子模块commit哈希已变更，但未先推送该变更到远程，导致release插件推送版本更新时，远程仓库的子模块引用与本地不一致，触发冲突

解决方案步骤 #

1. 配置子模块绑定固定分支 #

编辑根项目的.gitmodules文件，为子模块添加分支绑定，确保拉取时自动切换到指定分支：

[submodule "proj-submodule"]
    path = proj-submodule
    url = git@github.com:user1234/proj-submodule.git
    branch = master  # 替换为你的目标分支

同步配置并拉取子模块最新分支代码：

git submodule sync
git submodule update --remote --merge

2. 配置Maven Release插件支持子模块 #

在根项目pom.xml中，为maven-release-plugin添加子模块更新配置：

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-release-plugin</artifactId>
    <version>3.0.0-M7</version>
    <configuration>
        <commitByProject>true</commitByProject>
        <updateSubmodules>true</updateSubmodules> <!-- 启用子模块版本同步更新 -->
        <pushChanges>true</pushChanges>
        <remoteTagging>true</remoteTagging>
    </configuration>
</plugin>

3. 完整发布准备流程 #

# 1. 克隆根项目
git clone git@github.com:user1234/proj-root.git
cd proj-root

# 2. 初始化并同步子模块到指定分支
git submodule init
git submodule sync
git submodule update --remote --merge

# 3. 确认子模块处于正确分支
cd proj-submodule
git branch  # 应显示当前为绑定的分支（如* master）
cd ..

# 4. 执行release准备（可先加-DpushChanges=false本地验证）
mvn --batch-mode -DcommitByProject=true -DupdateSubmodules=true release:prepare

# 5. 执行发布（验证无误后）
mvn release:perform

额外注意事项 #

• 确保子模块版本与根项目版本通过Maven父子继承或依赖管理保持一致
• 执行release前，根项目和子模块仓库均需无未提交改动
• 若子模块为独立维护的项目，建议先完成子模块的版本发布，再更新根项目中子模块的依赖版本，最后执行根项目的release流程

内容的提问来源于stack exchange，提问作者Devloper