Jenkins 流水线中的变量详解

📄 Jenkins 流水线中的变量详解

Jenkins Pipeline 支持多种类型的变量使用方式，主要包括 内置环境变量、用户自定义变量 和 作用域相关的变量。了解这些变量的使用方式对于编写稳定、可维护的流水线至关重要。

一、Jenkins 内置环境变量（Built-in Environment Variables）

Jenkins 提供了一组预定义的环境变量，可以通过 env.变量名 的方式访问。这些变量通常用于获取当前构建信息、节点信息等。

常见内置变量列表：

使用方式：

echo "当前构建任务名称：${env.JOB_NAME}"
echo "工作空间路径：${env.WORKSPACE}"

二、临时变量（Local Variables）

在 Groovy 脚本中，你可以定义局部变量来存储中间值或配置参数。

定义和使用：

def workspacePath = env.WORKSPACE
def customVar = "MyCustomValue"

echo "工作空间路径是：${workspacePath}"
echo "自定义变量值为：${customVar}"

⚠️ 注意：

• 局部变量只在当前脚本块内有效。
• 不建议在多个 stage 中重复定义同名变量，容易引起混乱。

三、全局变量（Global Variables）

你可以在整个流水线中共享一个变量，通过将变量定义在 script 块外部或使用 env. 设置环境变量实现。

方法一：使用 script 块定义全局变量

script {
    globalVar = "This is a global variable"
}

stage('Example') {
    script {
        echo "全局变量内容：${globalVar}"
    }
}

方法二：使用 env. 设置自定义环境变量

env.MY_CUSTOM_VAR = "Hello from Jenkins"

stage('Use Custom Env Var') {
    echo "自定义环境变量：${env.MY_CUSTOM_VAR}"
}

这种方式定义的变量在整个流水线生命周期内都可用，并且可以通过 bat 或 sh 等命令行工具访问。

四、变量的作用域和修改方式

1. 修改内置变量（不推荐）

虽然可以修改 env. 下的某些变量，但不推荐随意更改 Jenkins 自带变量，因为可能影响后续流程判断或插件行为。

env.BUILD_DISPLAY_NAME = "Build-${env.BUILD_NUMBER}-Stable" // 修改显示名称

2. 修改自定义变量

env.MY_CUSTOM_VAR = "New Value"
echo "修改后的值：${env.MY_CUSTOM_VAR}"

3. 修改局部变量

def counter = 0
counter = counter + 1
echo "计数器当前值：${counter}"

五、变量调用方式的区别：env. vs env:

1. env.变量名 —— 推荐使用

这是标准的 Groovy 表达式，适用于所有 Jenkins Pipeline 脚本，是最通用、最稳定的写法。

echo "任务名称：${env.JOB_NAME}"

2. env:变量名 —— 仅用于 Declarative Pipeline 的 environment 块

这种写法只能在声明式流水线的 environment 块中使用，用于传递 Jenkins 环境变量到某个步骤或容器中。

示例：

pipeline {
    agent any
    environment {
        MY_ENV_VAR = env.JOB_NAME
    }
    stages {
        stage('Print Env') {
            steps {
                echo "MY_ENV_VAR=${env.MY_ENV_VAR}"
            }
        }
    }
}

❗ 区别总结：

• env. 是标准的 Groovy 变量访问方式，适用于所有脚本类型（Scripted / Declarative）
• env:变量名 仅在 Declarative Pipeline 的 environment 块中使用，不能直接用于 steps 中

六、变量在流水线中的典型使用场景

1. 动态路径拼接

def logDir = "${env.WORKSPACE}\\log\\build_${env.BUILD_NUMBER}"
bat "mkdir ${logDir}"

2. 控制流程分支

if (env.BRANCH_NAME == 'main') {
    echo "正在部署生产环境..."
} else {
    echo "正在部署测试环境..."
}

3. 日志记录与调试

echo "当前构建由 ${env.USERNAME} 触发"
echo "构建 URL: ${env.BUILD_URL}"

4. 作为参数传递给其他脚本或工具

bat """
    @echo on
    python my_script.py --workspace "${env.WORKSPACE}" --build-number ${env.BUILD_NUMBER}
"""

你提到的文章中关于 Jenkins Pipeline 的变量使用确实缺少了通过 parameters 定义变量的章节。我们可以通过添加一个专门的章节来完善文档内容。

以下是一个完整的补充内容，帮助你在文章中加入对 parameters 的讲解：

七、通过 parameters 定义参数化构建变量

Jenkins 支持通过 参数化构建（Parameterized Build）的方式，在启动流水线时动态传入变量值。这些参数可以在流水线运行时由用户输入或由其他系统传递进来，极大地增强了流水线的灵活性和可复用性。

常见参数类型包括：

注意：[file] 类型不适用于 Declarative Pipeline 的 parameters 块中。

使用方式（Declarative Pipeline 示例）：

pipeline {
    agent any

    parameters {
        string(name: 'ENVIRONMENT', defaultValue: 'test', description: '部署环境名称')
        booleanParam(name: 'DEPLOY_ENABLED', defaultValue: true, description: '是否启用部署')
        choice(name: 'BRANCH_NAME', choices: ['main', 'develop', 'feature-branch'], description: '选择要构建的 Git 分支')
        password(name: 'SECRET_KEY', defaultValue: 'defaultPass', description: '用于认证的密钥')
        text(name: 'NOTES', defaultValue: '无备注信息', description: '本次构建的备注说明')
    }

    stages {
        stage('Print Parameters') {
            steps {
                echo "当前部署环境：${params.ENVIRONMENT}"
                echo "是否启用部署：${params.DEPLOY_ENABLED}"
                echo "Git 分支名称：${params.BRANCH_NAME}"
                echo "密钥长度：${params.SECRET_KEY.size()}" // 避免直接打印密码
                echo "备注信息：${params.NOTES}"
            }
        }
    }
}

在 Scripted Pipeline 中使用参数：

properties([
    parameters([
        string(name: 'APP_VERSION', defaultValue: '1.0.0', description: '应用版本号'),
        booleanParam(name: 'IS_HOTFIX', defaultValue: false)
    ])
])

node {
    echo "应用版本：${params.APP_VERSION}"
    echo "是否为热修复版本：${params.IS_HOTFIX}"
}

使用场景示例：

1. 动态选择部署环境

stage('Deploy') {
    when {
        expression { params.DEPLOY_ENABLED }
    }
    steps {
        script {
            if (params.ENVIRONMENT == 'prod') {
                echo "正在部署到生产环境..."
                // 执行生产环境部署逻辑
            } else {
                echo "正在部署到测试环境..."
                // 执行测试环境部署逻辑
            }
        }
    }
}

2. 结合 Git 拉取指定分支代码

stage('Checkout') {
    steps {
        git branch: "${params.BRANCH_NAME}", url: 'https://your-repo-url.git'
    }
}

八、最佳实践建议

九、附录：常见问题排查技巧

1. 查看所有环境变量

script {
    env.each { key, value ->
        println "${key} = ${value}"
    }
}

2. 检查变量是否为空

if (!env.MY_VAR) {
    echo "警告：MY_VAR 未设置！"
}

3. 获取变量长度

def varLength = env.JOB_NAME.size()
echo "JOB_NAME 长度为：${varLength}"