任务参数化 #

参数化构建允许在触发构建时传入参数，使构建更加灵活和可配置。本节将详细介绍各种参数类型和使用方法。

参数类型概览 #

参数类型	说明	适用场景
String	字符串参数	版本号、分支名
Boolean	布尔参数	开关选项
Choice	选择参数	环境选择
Password	密码参数	敏感信息
File	文件参数	配置文件上传
Run	构建参数	引用其他构建
Text	多行文本	脚本内容

Freestyle项目参数化 #

配置参数 #

进入任务配置页面
勾选 This project is parameterized
点击 Add Parameter 添加参数

String参数 #

text

Add Parameter → String Parameter

Name: VERSION
Default Value: 1.0.0
Description: 应用版本号
Trim: ☑ (去除首尾空格)

Boolean参数 #

text

Add Parameter → Boolean Parameter

Name: DEPLOY
Default Value: true
Description: 是否部署到测试环境

Choice参数 #

text

Add Parameter → Choice Parameter

Name: ENVIRONMENT
Choices:
  dev
  test
  staging
  prod
Description: 部署环境

Password参数 #

text

Add Parameter → Password Parameter

Name: DB_PASSWORD
Default Value: 
Description: 数据库密码

File参数 #

text

Add Parameter → File Parameter

Name: CONFIG_FILE
File Location: config.yaml
Description: 配置文件

Run参数 #

text

Add Parameter → Run Parameter

Name: UPSTREAM_BUILD
Project Name: upstream-job
Description: 选择上游构建

Text参数 #

text

Add Parameter → Text Parameter

Name: SCRIPT_CONTENT
Default Value: |
  #!/bin/bash
  echo "Hello World"
Description: 脚本内容

使用参数 #

Shell脚本中使用 #

bash

#!/bin/bash

echo "=== 构建参数 ==="
echo "版本: ${VERSION}"
echo "环境: ${ENVIRONMENT}"
echo "部署: ${DEPLOY}"
echo "数据库密码: ${DB_PASSWORD}"

if [ "${DEPLOY}" = "true" ]; then
    echo "执行部署..."
    kubectl set image deployment/myapp myapp=myapp:${VERSION}
fi

Windows批处理中使用 #

batch

@echo off
echo === 构建参数 ===
echo 版本: %VERSION%
echo 环境: %ENVIRONMENT%
echo 部署: %DEPLOY%

if "%DEPLOY%"=="true" (
    echo 执行部署...
)

条件判断 #

bash

#!/bin/bash

case "${ENVIRONMENT}" in
    dev)
        echo "部署到开发环境"
        SERVER="dev.example.com"
        ;;
    test)
        echo "部署到测试环境"
        SERVER="test.example.com"
        ;;
    staging)
        echo "部署到预发布环境"
        SERVER="staging.example.com"
        ;;
    prod)
        echo "部署到生产环境"
        SERVER="prod.example.com"
        ;;
esac

echo "目标服务器: ${SERVER}"

Pipeline参数化 #

基本语法 #

groovy

pipeline {
    agent any
    
    parameters {
        string(name: 'VERSION', defaultValue: '1.0.0', description: '应用版本号')
        booleanParam(name: 'DEPLOY', defaultValue: true, description: '是否部署')
        choice(name: 'ENVIRONMENT', choices: ['dev', 'test', 'prod'], description: '部署环境')
        password(name: 'DB_PASSWORD', defaultValue: '', description: '数据库密码')
        text(name: 'NOTES', defaultValue: '', description: '构建说明')
    }
    
    stages {
        stage('Build') {
            steps {
                echo "版本: ${params.VERSION}"
                echo "环境: ${params.ENVIRONMENT}"
                echo "部署: ${params.DEPLOY}"
            }
        }
    }
}

完整示例 #

groovy

pipeline {
    agent any
    
    parameters {
        string(
            name: 'APP_NAME',
            defaultValue: 'myapp',
            description: '应用名称',
            trim: true
        )
        
        string(
            name: 'VERSION',
            defaultValue: '1.0.0',
            description: '应用版本号'
        )
        
        choice(
            name: 'ENVIRONMENT',
            choices: ['dev', 'test', 'staging', 'prod'],
            description: '部署环境'
        )
        
        booleanParam(
            name: 'SKIP_TESTS',
            defaultValue: false,
            description: '跳过测试'
        )
        
        booleanParam(
            name: 'DEPLOY',
            defaultValue: true,
            description: '是否部署'
        )
        
        password(
            name: 'DOCKER_PASSWORD',
            defaultValue: '',
            description: 'Docker仓库密码'
        )
        
        text(
            name: 'RELEASE_NOTES',
            defaultValue: '',
            description: '发布说明'
        )
    }
    
    environment {
        DOCKER_REGISTRY = 'registry.example.com'
    }
    
    stages {
        stage('Info') {
            steps {
                echo "=========================================="
                echo "构建参数"
                echo "=========================================="
                echo "应用名称: ${params.APP_NAME}"
                echo "版本号: ${params.VERSION}"
                echo "环境: ${params.ENVIRONMENT}"
                echo "跳过测试: ${params.SKIP_TESTS}"
                echo "部署: ${params.DEPLOY}"
                echo "=========================================="
            }
        }
        
        stage('Build') {
            steps {
                sh """
                    echo "构建应用 ${params.APP_NAME}:${params.VERSION}"
                    mvn clean package -DskipTests=${params.SKIP_TESTS}
                """
            }
        }
        
        stage('Test') {
            when {
                expression { return !params.SKIP_TESTS }
            }
            steps {
                sh 'mvn test'
            }
        }
        
        stage('Docker Build') {
            steps {
                sh """
                    docker build -t ${DOCKER_REGISTRY}/${params.APP_NAME}:${params.VERSION} .
                """
            }
        }
        
        stage('Docker Push') {
            steps {
                withCredentials([usernamePassword(
                    credentialsId: 'docker-credentials',
                    usernameVariable: 'DOCKER_USER',
                    passwordVariable: 'DOCKER_PASS'
                )]) {
                    sh """
                        docker login -u ${DOCKER_USER} -p ${DOCKER_PASS} ${DOCKER_REGISTRY}
                        docker push ${DOCKER_REGISTRY}/${params.APP_NAME}:${params.VERSION}
                    """
                }
            }
        }
        
        stage('Deploy') {
            when {
                expression { return params.DEPLOY }
            }
            steps {
                sh """
                    kubectl set image deployment/${params.APP_NAME} \
                        ${params.APP_NAME}=${DOCKER_REGISTRY}/${params.APP_NAME}:${params.VERSION} \
                        -n ${params.ENVIRONMENT}
                """
            }
        }
    }
    
    post {
        success {
            echo "构建成功！"
            echo "发布说明: ${params.RELEASE_NOTES}"
        }
    }
}

参数验证 #

使用when条件 #

groovy

stage('Deploy to Production') {
    when {
        expression { 
            return params.ENVIRONMENT == 'prod' && params.DEPLOY == true 
        }
    }
    steps {
        sh 'kubectl apply -f k8s/production/'
    }
}

使用input确认 #

groovy

stage('Deploy to Production') {
    when {
        expression { params.ENVIRONMENT == 'prod' }
    }
    steps {
        input {
            message "确认部署到生产环境？"
            ok "确认部署"
            parameters {
                string(name: 'CONFIRM', defaultValue: '', description: '输入 "CONFIRM" 确认')
            }
        }
        
        script {
            if (env.CONFIRM != 'CONFIRM') {
                error('部署未确认')
            }
        }
        
        sh 'kubectl apply -f k8s/production/'
    }
}

脚本验证 #

groovy

stage('Validate') {
    steps {
        script {
            if (!params.VERSION.matches('\\d+\\.\\d+\\.\\d+')) {
                error("版本号格式错误，应为 x.x.x")
            }
            
            if (params.ENVIRONMENT == 'prod' && !params.VERSION.endsWith('.0')) {
                error("生产环境只能部署正式版本 (x.x.0)")
            }
        }
    }
}

动态参数 #

Active Choices插件 #

安装 Active Choices Plugin 后可以创建动态参数：

groovy

properties([
    parameters([
        [
            $class: 'ChoiceParameter',
            name: 'PROJECT',
            choiceType: 'PT_SINGLE_SELECT',
            description: '选择项目',
            script: [
                $class: 'GroovyScript',
                script: [
                    classpath: [],
                    sandbox: true,
                    script: '''
                        return ['project-a', 'project-b', 'project-c']
                    '''
                ]
            ]
        ],
        [
            $class: 'CascadeChoiceParameter',
            name: 'BRANCH',
            referencedParameters: 'PROJECT',
            choiceType: 'PT_SINGLE_SELECT',
            description: '选择分支',
            script: [
                $class: 'GroovyScript',
                script: [
                    classpath: [],
                    sandbox: true,
                    script: '''
                        def project = PROJECT
                        if (project == 'project-a') {
                            return ['main', 'develop', 'feature-1']
                        } else if (project == 'project-b') {
                            return ['main', 'develop']
                        } else {
                            return ['main']
                        }
                    '''
                ]
            ]
        ]
    ])
])

pipeline {
    agent any
    stages {
        stage('Build') {
            steps {
                echo "项目: ${params.PROJECT}"
                echo "分支: ${params.BRANCH}"
            }
        }
    }
}

远程触发带参数 #

curl方式 #

bash

curl -X POST \
  -u username:api-token \
  "http://JENKINS_URL/job/my-job/buildWithParameters?VERSION=2.0.0&ENVIRONMENT=prod&DEPLOY=true"

POST JSON方式 #

bash

curl -X POST \
  -H "Content-Type: application/json" \
  -u username:api-token \
  -d '{"VERSION": "2.0.0", "ENVIRONMENT": "prod", "DEPLOY": true}' \
  "http://JENKINS_URL/job/my-job/buildWithParameters"

Python方式 #

python

import requests
from requests.auth import HTTPBasicAuth

JENKINS_URL = 'http://jenkins.example.com'
JOB_NAME = 'my-job'

params = {
    'VERSION': '2.0.0',
    'ENVIRONMENT': 'prod',
    'DEPLOY': True
}

response = requests.post(
    f'{JENKINS_URL}/job/{JOB_NAME}/buildWithParameters',
    params=params,
    auth=HTTPBasicAuth('username', 'api-token')
)

print(f"Status: {response.status_code}")

参数最佳实践 #

1. 提供默认值 #

groovy

parameters {
    string(name: 'VERSION', defaultValue: '1.0.0', description: '版本号')
}

2. 添加描述 #

groovy

parameters {
    choice(
        name: 'ENVIRONMENT',
        choices: ['dev', 'test', 'prod'],
        description: '''部署环境:
dev - 开发环境
test - 测试环境
prod - 生产环境'''
    )
}

3. 验证参数 #

groovy

stage('Validate') {
    steps {
        script {
            assert params.VERSION =~ /^\d+\.\d+\.\d+$/
            assert params.ENVIRONMENT in ['dev', 'test', 'prod']
        }
    }
}

4. 敏感信息使用凭据 #

groovy

stage('Deploy') {
    steps {
        withCredentials([usernamePassword(
            credentialsId: 'db-credentials',
            usernameVariable: 'DB_USER',
            passwordVariable: 'DB_PASS'
        )]) {
            sh 'mysql -u ${DB_USER} -p${DB_PASS}'
        }
    }
}

5. 使用参数化构建矩阵 #

groovy

pipeline {
    agent any
    parameters {
        booleanParam(name: 'BUILD_LINUX', defaultValue: true)
        booleanParam(name: 'BUILD_WINDOWS', defaultValue: true)
        booleanParam(name: 'BUILD_MAC', defaultValue: true)
    }
    stages {
        stage('Build') {
            parallel {
                stage('Linux') {
                    when { expression { params.BUILD_LINUX } }
                    steps { echo 'Building on Linux' }
                }
                stage('Windows') {
                    when { expression { params.BUILD_WINDOWS } }
                    steps { echo 'Building on Windows' }
                }
                stage('Mac') {
                    when { expression { params.BUILD_MAC } }
                    steps { echo 'Building on Mac' }
                }
            }
        }
    }
}

下一步学习 #

流水线基础 - Pipeline详解
凭据管理 - 安全管理凭据
实战案例 - 完整CI/CD流程

小结 #

参数化使构建更加灵活
支持多种参数类型
Pipeline中使用params访问参数
可以进行参数验证
敏感信息应使用凭据管理
支持动态参数和级联选择