Jenkins Pipeline无法检出正确Git子模块代码该如何配置？

架构老林

2026-8-29

问题原因

当前Jenkins GitSCM配置未显式开启子模块远程拉取、强制更新策略，默认会复用Jenkins节点本地缓存的子模块提交版本，不会主动拉取子模块远程仓库的最新变更，导致子模块代码始终停留在旧版本。

修复方式

在现有SubmoduleOption配置块中补充缺失的配置项即可，其余原有配置无需改动：

新增updateSubmodules: true：显式触发子模块更新流程
新增remoteSubmoduleFetch: true：强制每次构建从子模块远程仓库拉取最新提交记录，不使用本地缓存
新增cleanSubmodules: true：更新子模块前清理子模块目录下的本地修改、未跟踪文件，避免拉取冲突
若需要拉取子模块对应追踪分支的最新HEAD（而非主仓库当前commit绑定的固定子模块版本），将现有trackingSubmodules: false改为trackingSubmodules: true即可；如果需求是拉取主仓库记录的对应子模块版本，该项保持原有false配置。

修改后完整checkout代码

checkout(
    [$class: 'GitSCM',
    branches: [[name: '*/drop1']],
    doGenerateSubmoduleConfigurations: false,
    extensions: [[$class: 'SubmoduleOption',
    disableSubmodules: false,
    parentCredentials: true,
    recursiveSubmodules: true,
    reference: '',
    trackingSubmodules: false,
    // 新增以下3项配置
    updateSubmodules: true,
    remoteSubmoduleFetch: true,
    cleanSubmodules: true
    ], [$class: 'RelativeTargetDirectory', 
    relativeTargetDir: '']],
    submoduleCfg: [],
    userRemoteConfigs: [[url: 'https://xxxxxxx.git', credentialsId: 'xxxxxxxxxx' ]]] 
)

如果配置完成后仍存在旧缓存导致的拉取异常，可以在checkout步骤前新增一行命令清理本地子模块git缓存：