git-commit-id-plugin特定部署环境未生成git.properties问题排查

我在Maven构建中使用2.2.4版本的git-commit-id-plugin生成git.properties文件，多数环境运行正常，但在某一部署环境中该文件未生成，且无法定位原因。

插件配置 #

<plugin>
    <groupId>pl.project13.maven</groupId>
    <artifactId>git-commit-id-plugin</artifactId>
    <version>2.2.4</version>
    <executions>
        <execution>
            <phase>initialize</phase>
            <id>get-the-git-infos</id>
            <goals>
                <goal>revision</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <dotGitDirectory>${project.basedir}/.git</dotGitDirectory>
        <prefix>git</prefix>
        <verbose>true</verbose>
        <generateGitPropertiesFile>true</generateGitPropertiesFile>
        <generateGitPropertiesFilename>${project.basedir}/webapp/WEB-INF/git.properties</generateGitPropertiesFilename>
        <gitDescribe>
            <skip>false</skip>
            <always>false</always>
            <dirty>-dirty</dirty>
        </gitDescribe>
    </configuration>
</plugin>

已排查内容 #

• 项目根目录存在.git目录
• Maven构建无报错
• 其他环境可正常生成该文件

问题解答 #

1. 插件为何在该环境静默跳过git.properties生成？ #

可能的原因包括：

• 目标目录（webapp/WEB-INF）不存在或Maven运行用户无写入权限，插件无法创建文件但未抛出错误
• 该环境的.git目录权限不足，插件无法读取完整的Git元数据
• 仓库是浅克隆状态，缺失足够的Git历史信息，2.2.4版本插件处理这种场景时会静默跳过
• 仓库处于detached HEAD状态，旧版本插件对这种情况的兼容性不佳

2. 插件依赖哪些特定条件或权限？ #

• 读取权限：必须能读取项目根目录下的.git目录及其内部核心文件（如HEAD、refs、objects等）
• 写入权限：必须能向配置的generateGitPropertiesFilename路径写入文件
• Git环境：依赖可用的Git环境（插件默认用JGit，也可配置用原生Git命令），且仓库是完整可用的Git仓库，无元数据损坏
• Maven生命周期：插件绑定的initialize阶段必须被正常执行，未被-Dskip等参数跳过

3. 浅克隆、CI流水线或只读文件系统是否会引发该问题？ #

• 浅克隆：会引发。浅克隆仅拉取最近少量提交，缺失完整Git元数据，2.2.4版本插件无法获取足够信息，会跳过文件生成
• CI流水线：可能引发。部分CI流水线会清理.git目录内容、使用detached HEAD状态，或构建用户权限受限，都可能导致插件失效
• 只读文件系统：会引发。若目标目录所在文件系统为只读，插件无法写入文件，自然不会生成git.properties，且旧版本插件可能无明确报错

4. 如何解决此问题？ #

• 检查权限与目录：确认${project.basedir}/webapp/WEB-INF目录存在，且Maven运行用户拥有该目录的写入权限
• 修复克隆方式：若使用浅克隆，改为完整克隆（CI中可去掉--depth参数，或设置--depth=0）
• 升级插件版本：2.2.4版本较老旧，升级到4.x等稳定新版本，这些版本对浅克隆、CI环境的兼容性更好，错误日志也更清晰
• 开启调试日志：Maven构建时添加-X参数，查看插件执行的详细日志，定位具体故障点
• 调整插件配置：若仓库处于detached HEAD状态，可尝试添加<failOnNoGitDirectory>false</failOnNoGitDirectory>配置（谨慎使用，避免掩盖真实问题）；也可配置使用原生Git：<useNativeGit>true</useNativeGit>，利用系统Git命令的兼容性

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