Jenkins声明式Pipeline如何循环配置Docker-Agent执行构建阶段

报错根因 #

报错本质是声明式与脚本式Pipeline语法的使用边界问题：

• agent {}、steps {}是声明式Pipeline专属的配置指令，只能在声明式语法规定的固定层级（比如pipeline顶层、stage顶层）使用，不能嵌入script {}块内的Groovy循环逻辑中
• script {}块内部执行的是脚本式Pipeline逻辑，没有内置识别agent声明块的DSL方法，因此会抛出找不到对应方法的异常。
  另外最初的循环代码还有个Groovy语法坑：单引号包裹的字符串不会替换${}变量插值，会直接把${item}作为stage名称原样输出。

方案1：脚本式Docker调用（兼容所有版本，灵活度高） #

保留外层声明式结构，在动态Stage内不使用声明式agent块，直接调用Docker Pipeline插件提供的脚本式API拉取镜像、在容器内执行步骤，和原来配置的reuseNode true效果完全一致，默认复用当前节点的工作区：

pipeline {
  agent { label 'docker' }

  stages {
    stage('多镜像构建') {
      steps {
        script {
          // 镜像列表统一维护，后续新增镜像直接修改这里即可
          def imageList = ['ubuntu:20.04', 'ubuntu:22.04']
          // 需要并行执行就定义任务Map，不需要就直接循环
          def runTasks = [:]

          imageList.each { img ->
            runTasks["Running on ${img}"] = {
              stage("Running on ${img}") {
                // 拉取镜像并在容器内执行步骤，等价于原声明式docker agent配置
                docker.image(img).inside('--entrypoint=') {
                  sh 'uname -a && bash --version'
                }
              }
            }
          }
          // 串行执行则删除runTasks相关定义，直接在each循环内写stage逻辑即可，不需要调用parallel
          parallel runTasks
        }
      }
    }
  }
}

如果需要给容器传额外参数（比如挂载目录、特权模式），直接在inside()方法的字符串参数中添加即可，例如docker.image(img).inside('-v /opt/data:/data --privileged') {}。

方案2：声明式原生Matrix矩阵（无语法混用问题，配置更简洁） #

如果Jenkins版本≥2.277.1、声明式Pipeline插件版本支持Matrix语法，优先用官方原生的矩阵阶段能力，不需要手写script循环，原生支持多维度遍历配置，完全避免语法混用问题：

pipeline {
  agent { label 'docker' }

  stages {
    stage('多镜像构建') {
      matrix {
        agent {
          docker {
            reuseNode true
            label 'docker'
            image "${BUILD_IMAGE}"
          }
        }
        // 定义遍历维度，所有镜像配置在这里
        axes {
          axis {
            name 'BUILD_IMAGE'
            values 'ubuntu:20.04', 'ubuntu:22.04'
          }
        }
        stages {
          stage('执行构建') {
            steps {
              sh 'uname -a && bash --version'
            }
          }
        }
      }
    }
  }
}

Matrix配置会自动为每个镜像生成独立的Stage，在BlueOcean等可视化界面上也能正常展示每个镜像的执行状态，不需要手写循环逻辑。

内容的提问来源于stack exchange，提问作者Völker Graf