环境变量 #

环境变量是Jenkins Pipeline中传递配置信息的重要方式，本节将详细介绍环境变量的类型、使用方法和最佳实践。

环境变量类型 #

内置环境变量 #

Jenkins提供丰富的内置环境变量：

变量	说明	示例
BUILD_NUMBER	构建编号	1, 2, 3…
BUILD_ID	构建ID	2026-03-28_10-00-00
BUILD_DISPLAY_NAME	构建显示名称	#1
JOB_NAME	任务名称	my-pipeline
JOB_BASE_NAME	任务基础名称	my-pipeline
JOB_URL	任务URL	http://localhost:8080/job/my-pipeline/
BUILD_URL	构建URL	http://localhost:8080/job/my-pipeline/1/
WORKSPACE	工作空间路径	/var/jenkins_home/workspace/my-pipeline
JENKINS_HOME	Jenkins主目录	/var/jenkins_home
JENKINS_URL	Jenkins URL	http://localhost:8080/
NODE_NAME	节点名称	master
NODE_LABELS	节点标签	linux docker
EXECUTOR_NUMBER	执行器编号	0
BRANCH_NAME	分支名称	main
CHANGE_ID	PR编号	42
GIT_COMMIT	Git提交ID	abc123…
GIT_BRANCH	Git分支	origin/main
GIT_URL	Git URL	https://github.com/…

使用内置变量 #

groovy

pipeline {
    agent any
    
    stages {
        stage('Info') {
            steps {
                echo "构建编号: ${BUILD_NUMBER}"
                echo "任务名称: ${JOB_NAME}"
                echo "工作空间: ${WORKSPACE}"
                echo "节点名称: ${NODE_NAME}"
                echo "Jenkins URL: ${JENKINS_URL}"
            }
        }
    }
}

定义环境变量 #

Pipeline级别 #

groovy

pipeline {
    agent any
    
    environment {
        APP_NAME = 'myapp'
        VERSION = "${BUILD_NUMBER}"
        DEPLOY_ENV = 'development'
    }
    
    stages {
        stage('Build') {
            steps {
                echo "Building ${APP_NAME} version ${VERSION}"
            }
        }
    }
}

Stage级别 #

groovy

pipeline {
    agent any
    
    stages {
        stage('Build') {
            environment {
                BUILD_ENV = 'production'
            }
            steps {
                echo "Building in ${BUILD_ENV}"
            }
        }
        
        stage('Deploy') {
            environment {
                DEPLOY_ENV = 'staging'
            }
            steps {
                echo "Deploying to ${DEPLOY_ENV}"
            }
        }
    }
}

动态环境变量 #

groovy

pipeline {
    agent any
    
    environment {
        GIT_COMMIT_SHORT = sh(script: 'git rev-parse --short HEAD', returnStdout: true).trim()
        VERSION = "${BUILD_NUMBER}-${GIT_COMMIT_SHORT}"
    }
    
    stages {
        stage('Build') {
            steps {
                echo "Building version ${VERSION}"
            }
        }
    }
}

使用工具 #

groovy

pipeline {
    agent any
    
    environment {
        JAVA_HOME = tool name: 'JDK 11', type: 'jdk'
        MAVEN_HOME = tool name: 'Maven 3.8', type: 'maven'
        PATH = "${env.JAVA_HOME}/bin:${env.MAVEN_HOME}/bin:${env.PATH}"
    }
    
    stages {
        stage('Build') {
            steps {
                sh 'java -version'
                sh 'mvn --version'
            }
        }
    }
}

凭据环境变量 #

使用credentials() #

groovy

pipeline {
    agent any
    
    environment {
        DB_PASSWORD = credentials('db-password')
        AWS_ACCESS_KEY = credentials('aws-access-key')
        SSH_KEY = credentials('ssh-private-key')
    }
    
    stages {
        stage('Deploy') {
            steps {
                sh "deploy.sh --password ${DB_PASSWORD}"
            }
        }
    }
}

凭据类型 #

用户名密码 #

groovy

environment {
    DOCKER_CREDS = credentials('docker-registry')
}

steps {
    sh "docker login -u ${DOCKER_CREDS_USR} -p ${DOCKER_CREDS_PSW}"
}

SSH私钥 #

groovy

environment {
    SSH_KEY = credentials('ssh-key')
}

steps {
    sh "ssh -i ${SSH_KEY} user@server"
}

证书 #

groovy

environment {
    CLIENT_CERT = credentials('client-cert')
}

文件 #

groovy

environment {
    KUBECONFIG = credentials('kube-config')
}

steps {
    sh 'kubectl get pods'
}

withEnv步骤 #

临时设置环境变量 #

groovy

steps {
    withEnv(['MY_VAR=value', 'ANOTHER_VAR=another']) {
        sh 'echo $MY_VAR'
        sh 'echo $ANOTHER_VAR'
    }
}

修改PATH #

groovy

steps {
    withEnv(['PATH+MAVEN=/opt/maven/bin']) {
        sh 'mvn clean package'
    }
}

多个环境变量 #

groovy

steps {
    withEnv([
        'JAVA_HOME=/usr/lib/jvm/java-11',
        'MAVEN_HOME=/opt/maven',
        'PATH+MAVEN=/opt/maven/bin'
    ]) {
        sh 'mvn clean package'
    }
}

全局环境变量 #

系统配置 #

进入 Manage Jenkins → System
找到 Global properties
勾选 Environment variables
添加键值对

在Pipeline中使用 #

groovy

pipeline {
    agent any
    
    stages {
        stage('Build') {
            steps {
                echo "Global var: ${env.GLOBAL_VAR}"
            }
        }
    }
}

通过脚本设置 #

groovy

import jenkins.model.*
import hudson.model.*

Jenkins.instance.globalNodeProperties.get(EnvironmentVariablesNodeProperty.class).envVars.put('MY_VAR', 'value')

环境变量作用域 #

text

┌─────────────────────────────────────────────────────────────┐
│                     全局环境变量                              │
│  Manage Jenkins → System → Global properties                │
├─────────────────────────────────────────────────────────────┤
│                     Pipeline环境变量                         │
│  environment { ... }                                        │
├─────────────────────────────────────────────────────────────┤
│                     Stage环境变量                            │
│  stage { environment { ... } }                              │
├─────────────────────────────────────────────────────────────┤
│                     withEnv环境变量                          │
│  withEnv([...]) { ... }                                     │
├─────────────────────────────────────────────────────────────┤
│                     内置环境变量                              │
│  BUILD_NUMBER, JOB_NAME, ...                                │
└─────────────────────────────────────────────────────────────┘

环境变量读取 #

直接访问 #

groovy

steps {
    echo "Build: ${BUILD_NUMBER}"
    echo "Job: ${JOB_NAME}"
}

使用env对象 #

groovy

steps {
    echo "Build: ${env.BUILD_NUMBER}"
    echo "Job: ${env.JOB_NAME}"
    
    script {
        def vars = env.getEnvironment()
        vars.each { k, v ->
            echo "${k} = ${v}"
        }
    }
}

默认值 #

groovy

steps {
    def myVar = env.MY_VAR ?: 'default'
    echo "Value: ${myVar}"
}

环境变量注入 #

注入到Shell脚本 #

groovy

steps {
    withEnv(['APP_NAME=myapp', 'VERSION=1.0']) {
        sh '''
            echo "App: ${APP_NAME}"
            echo "Version: ${VERSION}"
        '''
    }
}

注入到Windows批处理 #

groovy

steps {
    withEnv(['APP_NAME=myapp', 'VERSION=1.0']) {
        bat '''
            echo App: %APP_NAME%
            echo Version: %VERSION%
        '''
    }
}

注入到Docker容器 #

groovy

pipeline {
    agent {
        docker {
            image 'maven:3.8-openjdk-11'
            args '-e APP_NAME=myapp -e VERSION=1.0'
        }
    }
}

环境变量文件 #

从文件加载 #

groovy

steps {
    script {
        def props = readProperties file: 'env.properties'
        props.each { k, v ->
            env."${k}" = v
        }
    }
}

写入文件 #

groovy

steps {
    writeFile file: 'env.properties', text: """
        APP_NAME=myapp
        VERSION=${BUILD_NUMBER}
    """
}

dotenv插件 #

groovy

steps {
    withCredentials([file(credentialsId: 'env-file', variable: 'ENV_FILE')]) {
        load "${ENV_FILE}"
    }
}

环境变量最佳实践 #

1. 命名约定 #

groovy

environment {
    APP_NAME = 'myapp'           // 应用名称
    APP_VERSION = '1.0.0'        // 应用版本
    DEPLOY_ENV = 'production'    // 部署环境
    DB_HOST = 'localhost'        // 数据库主机
    DB_PORT = '3306'             // 数据库端口
}

2. 使用凭据存储敏感信息 #

groovy

environment {
    DB_PASSWORD = credentials('db-password')
    API_KEY = credentials('api-key')
}

3. 集中管理配置 #

groovy

def loadConfig(String env) {
    def config = [
        dev: [
            DB_HOST: 'dev-db.example.com',
            API_URL: 'https://dev-api.example.com'
        ],
        prod: [
            DB_HOST: 'prod-db.example.com',
            API_URL: 'https://api.example.com'
        ]
    ]
    return config[env]
}

pipeline {
    agent any
    
    environment {
        CONFIG = loadConfig(params.ENVIRONMENT)
    }
    
    stages {
        stage('Deploy') {
            steps {
                echo "DB: ${CONFIG.DB_HOST}"
                echo "API: ${CONFIG.API_URL}"
            }
        }
    }
}

4. 避免硬编码 #

groovy

// 不推荐
steps {
    sh 'deploy.sh --env production --db localhost'
}

// 推荐
environment {
    DEPLOY_ENV = 'production'
    DB_HOST = credentials('db-host')
}
steps {
    sh "deploy.sh --env ${DEPLOY_ENV} --db ${DB_HOST}"
}

完整示例 #

groovy

pipeline {
    agent any
    
    parameters {
        choice(name: 'ENVIRONMENT', choices: ['dev', 'staging', 'prod'], description: '部署环境')
    }
    
    environment {
        APP_NAME = 'myapp'
        VERSION = "${BUILD_NUMBER}"
        GIT_COMMIT_SHORT = sh(script: 'git rev-parse --short HEAD', returnStdout: true).trim()
        
        DOCKER_REGISTRY = 'registry.example.com'
        DOCKER_CREDS = credentials('docker-registry')
        
        KUBECONFIG = credentials('kube-config')
    }
    
    stages {
        stage('Load Config') {
            steps {
                script {
                    def configs = [
                        dev: [
                            namespace: 'dev',
                            replicas: '1',
                            resources: 'low'
                        ],
                        staging: [
                            namespace: 'staging',
                            replicas: '2',
                            resources: 'medium'
                        ],
                        prod: [
                            namespace: 'production',
                            replicas: '3',
                            resources: 'high'
                        ]
                    ]
                    
                    env.NAMESPACE = configs[params.ENVIRONMENT].namespace
                    env.REPLICAS = configs[params.ENVIRONMENT].replicas
                    env.RESOURCES = configs[params.ENVIRONMENT].resources
                }
            }
        }
        
        stage('Build') {
            environment {
                BUILD_ENV = 'production'
            }
            steps {
                echo "Building ${APP_NAME}:${VERSION}"
                echo "Commit: ${GIT_COMMIT_SHORT}"
                echo "Environment: ${params.ENVIRONMENT}"
                sh 'mvn clean package'
            }
        }
        
        stage('Docker') {
            steps {
                withEnv(["PATH+DOCKER=/usr/bin"]) {
                    sh "docker login -u ${DOCKER_CREDS_USR} -p ${DOCKER_CREDS_PSW} ${DOCKER_REGISTRY}"
                    sh "docker build -t ${DOCKER_REGISTRY}/${APP_NAME}:${VERSION} ."
                    sh "docker push ${DOCKER_REGISTRY}/${APP_NAME}:${VERSION}"
                }
            }
        }
        
        stage('Deploy') {
            steps {
                sh """
                    kubectl set image deployment/${APP_NAME} \
                        ${APP_NAME}=${DOCKER_REGISTRY}/${APP_NAME}:${VERSION} \
                        -n ${NAMESPACE}
                    
                    kubectl scale deployment/${APP_NAME} \
                        --replicas=${REPLICAS} \
                        -n ${NAMESPACE}
                """
            }
        }
    }
    
    post {
        always {
            echo "Build ${BUILD_NUMBER} completed"
            echo "Environment variables used:"
            script {
                echo "APP_NAME: ${APP_NAME}"
                echo "VERSION: ${VERSION}"
                echo "NAMESPACE: ${NAMESPACE}"
                echo "REPLICAS: ${REPLICAS}"
            }
        }
    }
}

下一步学习 #

凭据管理 - 安全管理敏感信息
构建工具 - 配置Maven、Gradle等工具
工作空间管理 - 管理构建工作空间

小结 #

环境变量是Pipeline配置的核心
支持内置、全局、Pipeline和Stage级别
使用credentials安全存储敏感信息
withEnv提供临时环境变量
遵循命名约定和最佳实践