### 如何在 Jenkins Pipeline 中正确配置和拉取 Git 子模块 为了在 Jenkins Pipeline 中成功拉取 Git 子模块，可以通过扩展 `checkout` 步骤中的参数来实现。以下是具体的解决方案： #### 解决方案 通过设置 `extensions` 参数，在其中加入 `$class: 'SubmoduleOption'` 来支持子模块的初始化和更新操作[^1]。 ```groovy pipeline { agent any stages { stage('Checkout with Submodules') { steps { script { checkout([ $class: 'GitSCM', branches: [[name: '*/main']], // 替换为目标分支名称 doGenerateSubmoduleConfigurations: false, extensions: [ [$class: 'SubmoduleOption', recursiveSubmodules: true, trackingSubmodules: true], [$class: 'CloneOption', depth: 1, honorRefspec: true, noTags: false, reference: '', shallow: true] ], userRemoteConfigs: [ [url: 'https://your-repo-url.git', credentialsId: 'your-credentials-id'] ] ]) } } } } } ``` 在此代码片段中： - 使用了 `[$class: 'SubmoduleOption']` 并设置了 `recursiveSubmodules: true` 和 `trackingSubmodules: true`，这表示递归地克隆所有子模块并跟踪它们的状态。 - 同时还加入了 `[$class: 'CloneOption']` 扩展选项用于优化克隆过程，例如浅克隆 (`shallow`) 或者禁用标签 (`noTags`) 的下载[^1]。 如果需要将整个仓库及其子模块放置在一个特定的工作目录下，则可以结合 `dir()` 函数完成此需求[^2]。 ```groovy stage('Custom Directory Checkout') { steps { dir('/path/to/custom/directory') { script { checkout([ $class: 'GitSCM', branches: [[name: '*/main']], doGenerateSubmoduleConfigurations: false, extensions: [ [$class: 'SubmoduleOption', recursiveSubmodules: true, trackingSubmodules: true] ], userRemoteConfigs: [ [url: 'https://your-repo-url.git', credentialsId: 'your-credentials-id'] ] ]) } } } } ``` 以上方法能够满足大多数场景下的子模块拉取需求。对于更复杂的定制化路径或者部分文件夹的选择性拉取情况，可进一步调整稀疏检出策略 (Sparse Checkout)[^4]。 #### 注意事项 确保 Jenkins 节点已安装最新版本的 Git 插件以及客户端工具，并验证所使用的凭证具有访问主库及各子模块资源的权限[^3]。 ---