CI/CD / 系统课时

用环境变量传递构建参数

用环境变量传递构建参数

流水线经常需要在多个步骤间传递分支名、版本号和构建参数。Jenkins 提供 environment、内置环境变量以及运行期赋值等不同来源。关键不是把所有值都放进环境变量,而是让变量在真正需要的范围内可见,并明确覆盖关系。

学习目标

  • 区分 environment、Jenkins 内置变量和运行期环境变量
  • 控制变量在整条 Pipeline、单个 Stage 或局部步骤中的作用范围
  • 在 Groovy 与 Shell 之间正确读取和传递变量

environment 声明固定构建环境

Declarative Pipeline 可以使用 environment 声明环境变量。放在 pipeline 层时,变量可供各个 Stage 使用;放在某个 stage 中时,则只服务于该 Stage。

下面的 Jenkinsfile 同时演示全局变量、Stage 变量和 Jenkins 提供的 BUILD_NUMBER。

groovy
pipeline {
    agent any

    environment {
        APP_NAME = 'order-api'
    }

    stages {
        stage('Build') {
            environment {
                BUILD_MODE = 'release'
            }
            steps {
                sh '''
                    printf 'app=%s\n' "$APP_NAME"
                    printf 'mode=%s\n' "$BUILD_MODE"
                    printf 'build=%s\n' "$BUILD_NUMBER"
                '''
            }
        }
    }
}

预期输出

text
app=order-api
mode=release
build=<ID>

<ID> 代表当前 Jenkins 构建编号,实际值随任务运行次数变化。APP_NAME 在整条 Pipeline 中可用,而 BUILD_MODE 的声明范围限制在 Build Stage。

Pipeline、Stage 与局部环境变量作用域关系

内置变量由 Jenkins 注入

Jenkins 会在构建环境中提供一组变量,例如 BUILD_NUMBER、BUILD_ID、BUILD_TAG、JOB_NAME 和 WORKSPACE。具体可用变量还可能受到 Jenkins 版本、任务类型和插件影响,因此流水线不应凭空假定某个插件变量一定存在。

需要查看当前构建实际拥有的环境变量时,可以执行 printenv。如果日志可能包含敏感信息,则不要无筛选地输出整个环境;应只检查需要的变量。

groovy
steps {
    sh '''
        printf 'JOB_NAME=%s\n' "$JOB_NAME"
        printf 'BUILD_NUMBER=%s\n' "$BUILD_NUMBER"
        printf 'WORKSPACE=%s\n' "$WORKSPACE"
    '''
}

预期输出

text
JOB_NAME=<ID>
BUILD_NUMBER=<ID>
WORKSPACE=<PATH>

<ID> 和 <PATH> 都由实际 Jenkins 任务与 Agent 决定。验证变量时应关注它是否存在以及值是否来自预期构建,而不是依赖某个固定路径或编号。

Groovy 与 Shell 的读取时机不同

在 Groovy Pipeline 代码中,可以通过 env 访问环境变量,例如 env.BUILD_NUMBER。Shell 则在进程启动后通过 $BUILD_NUMBER 读取传入的环境。

下面的片段示例需要放在 Declarative Pipeline 的 steps 中。Groovy 负责组合运行期版本字符串,再把结果交给后续 Shell。

groovy
script {
    env.IMAGE_TAG = "build-${env.BUILD_NUMBER}"
}
sh '''
    printf 'image=%s:%s\n' "$APP_NAME" "$IMAGE_TAG"
'''

预期输出

text
image=order-api:build-<ID>

这里使用三单引号包住 Shell,是为了让 $APP_NAME 和 $IMAGE_TAG 留给 Shell 展开。如果改用 Groovy 双引号字符串,就还要考虑 Groovy 自身的字符串插值,变量来源会更难判断。

临时变量缩小影响范围

某个变量只服务于一小段步骤时,没有必要提升到整条 Pipeline。Jenkins 的 withEnv 可以为闭包中的步骤临时增加或覆盖环境变量,离开闭包后恢复原环境。

下面是片段示例,需要放在 steps 的 script 块或支持该步骤的上下文中。

groovy
withEnv(['DEPLOY_ENV=staging']) {
    sh 'printf "target=%s\\n" "$DEPLOY_ENV"'
}

预期输出

text
target=staging

这种局部作用域适合临时工具参数、测试环境标记等值。稳定且跨 Stage 使用的非敏感配置更适合顶层 environment;只在单个 Stage 使用的配置则应尽量放到 Stage 范围。

不要把凭据当普通参数传递

环境变量使用方便,但不意味着敏感值应该直接写进 Jenkinsfile。密码、Token 和私钥应由 Jenkins Credentials 等凭据机制管理,并只在需要的步骤中绑定,而不是硬编码到 environment 或提交到 Git。

排查变量问题时,可以按“变量在哪里定义、作用域覆盖到哪里、由 Groovy 还是 Shell 展开、运行时是否真的存在”的顺序检查。这样能快速定位变量为空、被覆盖或只在错误 Stage 中可见的问题。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

用环境变量传递构建参数

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通