CI/CD / 系统课时
用环境变量传递构建参数
用环境变量传递构建参数
流水线经常需要在多个步骤间传递分支名、版本号和构建参数。Jenkins 提供 environment、内置环境变量以及运行期赋值等不同来源。关键不是把所有值都放进环境变量,而是让变量在真正需要的范围内可见,并明确覆盖关系。
学习目标
- 区分
environment、Jenkins 内置变量和运行期环境变量 - 控制变量在整条 Pipeline、单个 Stage 或局部步骤中的作用范围
- 在 Groovy 与 Shell 之间正确读取和传递变量
environment 声明固定构建环境
Declarative Pipeline 可以使用 environment 声明环境变量。放在 pipeline 层时,变量可供各个 Stage 使用;放在某个 stage 中时,则只服务于该 Stage。
下面的 Jenkinsfile 同时演示全局变量、Stage 变量和 Jenkins 提供的 BUILD_NUMBER。
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"
'''
}
}
}
}预期输出
app=order-api
mode=release
build=<ID><ID> 代表当前 Jenkins 构建编号,实际值随任务运行次数变化。APP_NAME 在整条 Pipeline 中可用,而 BUILD_MODE 的声明范围限制在 Build Stage。

内置变量由 Jenkins 注入
Jenkins 会在构建环境中提供一组变量,例如 BUILD_NUMBER、BUILD_ID、BUILD_TAG、JOB_NAME 和 WORKSPACE。具体可用变量还可能受到 Jenkins 版本、任务类型和插件影响,因此流水线不应凭空假定某个插件变量一定存在。
需要查看当前构建实际拥有的环境变量时,可以执行 printenv。如果日志可能包含敏感信息,则不要无筛选地输出整个环境;应只检查需要的变量。
steps {
sh '''
printf 'JOB_NAME=%s\n' "$JOB_NAME"
printf 'BUILD_NUMBER=%s\n' "$BUILD_NUMBER"
printf 'WORKSPACE=%s\n' "$WORKSPACE"
'''
}预期输出
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。
script {
env.IMAGE_TAG = "build-${env.BUILD_NUMBER}"
}
sh '''
printf 'image=%s:%s\n' "$APP_NAME" "$IMAGE_TAG"
'''预期输出
image=order-api:build-<ID>这里使用三单引号包住 Shell,是为了让 $APP_NAME 和 $IMAGE_TAG 留给 Shell 展开。如果改用 Groovy 双引号字符串,就还要考虑 Groovy 自身的字符串插值,变量来源会更难判断。
临时变量缩小影响范围
某个变量只服务于一小段步骤时,没有必要提升到整条 Pipeline。Jenkins 的 withEnv 可以为闭包中的步骤临时增加或覆盖环境变量,离开闭包后恢复原环境。
下面是片段示例,需要放在 steps 的 script 块或支持该步骤的上下文中。
withEnv(['DEPLOY_ENV=staging']) {
sh 'printf "target=%s\\n" "$DEPLOY_ENV"'
}预期输出
target=staging这种局部作用域适合临时工具参数、测试环境标记等值。稳定且跨 Stage 使用的非敏感配置更适合顶层 environment;只在单个 Stage 使用的配置则应尽量放到 Stage 范围。
不要把凭据当普通参数传递
环境变量使用方便,但不意味着敏感值应该直接写进 Jenkinsfile。密码、Token 和私钥应由 Jenkins Credentials 等凭据机制管理,并只在需要的步骤中绑定,而不是硬编码到 environment 或提交到 Git。
排查变量问题时,可以按“变量在哪里定义、作用域覆盖到哪里、由 Groovy 还是 Shell 展开、运行时是否真的存在”的顺序检查。这样能快速定位变量为空、被覆盖或只在错误 Stage 中可见的问题。