Jenkins Pipeline中参数化构建

在 Jenkins Pipeline 中，参数化构建（Parameterized Builds） 允许用户在触发任务时动态传入参数，从而实现更灵活的流程控制。以下是 声明式 Pipeline 和 脚本式 Pipeline 的参数化配置方法及示例：

---

1. 声明式 Pipeline 参数化设置

基本语法

在 pipeline 块外使用 parameters 指令定义参数：

pipeline {
    agent any
    parameters {
        // 参数定义在这里
    }
    stages {
        stage('Example') {
            steps {
                // 使用参数
            }
        }
    }
}

常用参数类型及示例

(1) 字符串参数（String）

parameters {
    string(name: 'DEPLOY_ENV', defaultValue: 'prod', description: '部署环境')
}

使用方式：

echo "部署环境: ${params.DEPLOY_ENV}"

(2) 布尔参数（Boolean）

parameters {
    booleanParam(name: 'DRY_RUN', defaultValue: true, description: '是否试运行')
}

使用方式：

if (params.DRY_RUN) {
    echo "试运行模式"
}

(3) 选择参数（Choice）

parameters {
    choice(
        name: 'ARCH',
        choices: ['x86', 'arm64', 'amd64'],
        description: 'CPU架构'
    )
}

使用方式：

sh "build --arch=${params.ARCH}"

(4) 文件参数（File）

parameters {
    file(name: 'CONFIG_FILE', description: '上传配置文件')
}

使用方式：

sh "cat ${params.CONFIG_FILE}"

(5) 密码参数（Password）

parameters {
    password(name: 'API_KEY', description: 'API密钥')
}

使用方式：

withCredentials([string(credentialsId: 'API_KEY', variable: 'SECRET')]) {
    sh "echo ${SECRET}"
}

---

2. 脚本式 Pipeline 参数化设置

使用 properties 方法定义参数：

properties([
    parameters([
        string(name: 'BRANCH', defaultValue: 'main', description: 'Git分支'),
        booleanParam(name: 'CLEAN_BUILD', defaultValue: false, description: '是否清理构建')
    ])
])

node {
    stage('Build') {
        echo "Building branch: ${params.BRANCH}"
        if (params.CLEAN_BUILD) {
            sh 'make clean'
        }
    }
}

---

3. 动态参数（Active Choices）

需要安装插件 "Active Choices"，支持动态生成参数（如根据 Git 分支列表生成选项）：

parameters {
    activeChoiceParam(name: 'BRANCH', script: [
        $class: 'GroovyScript',
        script: [
            script: 'return ["main", "dev", "feature/*"].join("\\n")',
            sandbox: true
        ],
        description: '选择Git分支'
    ])
}

---

4. 参数化触发构建

(1) 通过 build 步骤传递参数

build(
    job: 'downstream-job',
    parameters: [
        string(name: 'ENV', value: 'prod'),
        booleanParam(name: 'FORCE', value: true)
    ]
)

(2) 通过 input 步骤交互式输入

stage('Approval') {
    steps {
        script {
            def userInput = input(
                id: 'confirm',
                message: '确认部署？',
                parameters: [
                    choice(name: 'ENV', choices: 'prod\ndev', description: '环境')
                ]
            )
            echo "已选择环境: ${userInput}"
        }
    }
}

---

5. 参数默认值与环境变量

从环境变量获取默认值

parameters {
    string(name: 'BUILD_DIR', defaultValue: env.WORKSPACE, description: '构建目录')
}

参数组合使用

pipeline {
    parameters {
        string(name: 'VERSION', defaultValue: '1.0.0')
        choice(name: 'REPO', choices: ['docker', 'npm'])
    }
    stages {
        stage('Deploy') {
            steps {
                script {
                    def image = "${params.REPO}:${params.VERSION}"
                    sh "docker push ${image}"
                }
            }
        }
    }
}

---

6. 注意事项

1. 首次运行需手动触发：首次定义参数的 Pipeline 需要手动运行一次，参数才会生效。
2. 修改参数需更新任务 ：更改 parameters 后需通过 "Build with Parameters" 重新触发。
3. 参数作用域 ：params 是全局变量，可在所有 stage 中访问。
4. 敏感参数 ：密码类参数建议使用 Jenkins 的 Credentials Binding （withCredentials）。

---

完整示例

声明式 Pipeline

pipeline {
    agent any
    parameters {
        string(name: 'TAG', defaultValue: 'latest', description: '镜像版本')
        choice(name: 'ENV', choices: ['dev', 'prod'], description: '环境')
        booleanParam(name: 'RUN_TESTS', defaultValue: true, description: '是否运行测试')
    }
    stages {
        stage('Build') {
            steps {
                sh "docker build -t myapp:${params.TAG} ."
            }
        }
        stage('Test') {
            when { expression { params.RUN_TESTS } }
            steps {
                sh 'make test'
            }
        }
        stage('Deploy') {
            steps {
                sh "kubectl apply -f deploy/${params.ENV}.yaml"
            }
        }
    }
}

脚本式 Pipeline

properties([
    parameters([
        string(name: 'TAG', defaultValue: 'latest'),
        choice(name: 'ENV', choices: ['dev', 'prod']),
        booleanParam(name: 'RUN_TESTS', defaultValue: true)
    ])
])

node {
    stage('Build') {
        sh "docker build -t myapp:${params.TAG} ."
    }
    if (params.RUN_TESTS) {
        stage('Test') {
            sh 'make test'
        }
    }
    stage('Deploy') {
        sh "kubectl apply -f deploy/${params.ENV}.yaml"
    }
}

---

通过参数化设置，你可以轻松实现 动态构建策略，如：

• 根据参数选择不同环境部署（dev/prod）。
• 控制是否跳过测试或代码扫描。
• 动态传入版本号、分支名等。