当前位置：首页 > news >正文

Jenkins Pipeline中参数化构建

news 2025/8/17 6:54:37

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

1. 声明式 Pipeline 参数化设置

基本语法

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

pipeline {agent anyparameters {// 参数定义在这里}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. 注意事项

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

完整示例

声明式 Pipeline

pipeline {agent anyparameters {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"}
}