Jenkins Pipeline中如何通过用户输入参数化Docker Agent镜像标签

问题背景 #

在使用Docker Agent的Jenkins流水线中，需要允许用户指定镜像仓库的镜像标签。尝试在Groovy的call方法中定义默认值为latest的tag参数，拼接后传入Docker Agent的image参数，但运行时报错，且变量未被正确解析，传入了字面量"tag"。

原尝试代码：

#!/usr/bin/env groovy

def call(String tag = 'latest') {
    pipeline {
        agent {
            docker {
                image "analytics/rsc:${tag}"
                registryUrl 'my.local.registry'
                // 其他配置
            }
        }
        // 流水线步骤
    }
}

报错信息：

...12: Invalid config option "call" for agent type "docker". Valid config options are [image, alwaysPull, args, containerPerStageRoot, customWorkspace, label, registryCredentialsId, registryUrl, reuseNode] @ line 12, column 17.
                   image analytics/rsc:${tag}

问题原因 #

Jenkins声明式流水线的agent配置块属于DSL语法，并非纯Groovy代码执行环境。直接在image字段中使用Groovy变量插值，会被DSL解析器误判为无效配置项，而不会执行变量替换，导致报错或变量未解析。

解决方案 #

方案1：使用脚本式Agent（推荐） #

通过script块在Agent中执行Groovy代码，手动拉取并使用指定镜像：

#!/usr/bin/env groovy

def call(String tag = 'latest') {
    pipeline {
        agent {
            script {
                // 拼接完整镜像名并拉取
                def targetImage = docker.image("analytics/rsc:${tag}")
                targetImage.pull()
                // 在容器内执行流水线步骤，可添加启动参数
                targetImage.inside {
                    // 示例：自定义容器参数
                    // targetImage.inside('-v /host/path:/container/path')
                }
            }
        }
        stages {
            stage('Build') {
                steps {
                    echo "当前使用镜像标签: ${tag}"
                    // 你的构建/测试步骤
                }
            }
        }
    }
}

方案2：提前拼接镜像名再传入声明式Agent #

在pipeline块外部提前拼接好完整镜像名，再在声明式Agent中直接引用：

#!/usr/bin/env groovy

def call(String tag = 'latest') {
    // 先在Groovy环境中拼接完整镜像名
    def fullImage = "analytics/rsc:${tag}"
    
    pipeline {
        agent {
            docker {
                image fullImage
                registryUrl 'my.local.registry'
                // 可选：关联私有仓库凭据
                // registryCredentialsId 'your-registry-creds'
            }
        }
        stages {
            stage('Build') {
                steps {
                    echo "当前使用镜像: ${fullImage}"
                    // 你的流水线步骤
                }
            }
        }
    }
}

注意事项 #

• 使用私有镜像仓库时，需配置registryCredentialsId参数，关联Jenkins中存储的仓库凭据。
• 方案1的inside方法支持添加容器启动参数，满足自定义容器挂载、端口映射等需求。

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