Jenkins Pipeline 变量打印指南

调试 Jenkins Pipeline 时，最让人抓狂的不是"代码错了"，而是"变量到底有没有传进来"------params.BRANCH 在 shell 里读不到？environment 定义的 VERSION 被谁覆盖了？credentials() 注入的密码到底叫什么名字？这些问题用猜的是猜不出来的，得"看"。本文用一段 30 行的声明式 Pipeline 脚本，搭一个"变量探针"，让流水线运行时的所有环境变量和参数一目了然。

一、为什么需要"变量探针"

调试 Jenkins Pipeline 时，下面这些问题反复出现：

现象	你想知道的
shell 里 $BRANCH 取不到值	这个变量到底有没有注入到容器里
environment 定义的 VERSION 行为异常	是不是被系统变量覆盖了
credentials() 注入的 SSH 私钥叫什么	注入后的环境变量名是什么
不同 Job 同样的 Pipeline 行为不一致	节点环境差异在哪
镜像里 PATH 不对	容器内 PATH 实际指向哪里

光靠"读代码 + 猜"是猜不出来的，唯一可靠的办法就是把所有变量打印出来看一眼 。这就是"变量探针"的价值------一段 30 行的脚本，让你看清

Pipeline 运行时的"内部气候"。

二、最小可用脚本

pipeline {
    agent none

    parameters {
        string(name: 'BRANCH', defaultValue: 'main', description: 'Branch to build')
        booleanParam(name: 'RUN_TESTS', defaultValue: true, description: 'Run tests?')
    }

    environment {
        NODE_ENV = 'production'
        VERSION = '1.0.0'
    }

    stages {
        stage('打印变量') {
            agent {
                docker {
                    image 'python:3.11'
                }
            }
            steps {
                echo "================ 开始打印 ================"
                sh 'printenv | sort'
                echo "================ 打印结束 ================"
            }
        }
    }
}

---

三. printenv | sort ------ 探针核心

• printenv：列出当前所有环境变量
• sort：按字母排序，便于查看

---

四、运行后的输出长什么样

执行后 Jenkins 日志会输出类似内容：

================ 开始打印 ================
BRANCH=main                                    ← parameters 注入
BUILD_ID=12
BUILD_NUMBER=12
BUILD_URL=https://jenkins.example.com/job/demo/12/
HOME=/root
JENKINS_HOME=/var/lib/jenkins
JENKINS_URL=https://jenkins.example.com/
JOB_NAME=demo
NODE_ENV=production                            ← environment 定义
RUN_TESTS=true                                ← parameters 注入
VERSION=1.0.0                                  ← environment 定义
WORKSPACE=/var/lib/jenkins/workspace/demo
...
================ 打印结束 ================

关键观察点：

1. BRANCH=main ------ parameters 自动注入为环境变量
2. NODE_ENV=production ------ environment 块定义的变量也注入成功
3. WORKSPACE / JENKINS_HOME ------ Jenkins 系统变量，可用来构造路径

---

五、5 种实用改法

改法 1：分类打印，便于阅读

sh '''
    echo "===== 用户参数 ====="
    echo "BRANCH = $BRANCH"
    echo "RUN_TESTS = $RUN_TESTS"

    echo "===== 自定义环境变量 ====="
    echo "NODE_ENV = $NODE_ENV"
    echo "VERSION = $VERSION"

    echo "===== 全部环境变量 ====="
    printenv | sort
'''

改法 2：屏蔽敏感字段（凭证密码等）

sh 'printenv | sort | grep -v -iE "PASSWORD|SECRET|TOKEN|KEY|PSW|USR"'

避免 credentials() 注入的密码以明文出现在日志。

改法 3：用 Groovy 遍历 params

script {
    echo "===== 用户参数（Groovy 视角）====="
    params.each { k, v ->
        echo "${k} = ${v}"
    }
}

改法 4：只看自己定义的变量（白名单）

sh '''
    echo "BRANCH=$BRANCH"
    echo "RUN_TESTS=$RUN_TESTS"
    echo "NODE_ENV=$NODE_ENV"
    echo "VERSION=$VERSION"
'''

不做全量 printenv，最安全。

改法 5：归档快照，便于事后追溯

sh 'printenv | sort > env-snapshot.txt'
archiveArtifacts artifacts: 'env-snapshot.txt', allowEmptyArchive: true

跑完在 Jenkins UI 左侧"构建产物"里可下载 env-snapshot.txt。

---

六、parameters vs environment 输出差异

来源	在 printenv 中的表现	访问方式
parameters 中定义	自动成为环境变量，可直接 $X 读	params.X（Groovy） / $X（shell）
environment 中定义	自动成为环境变量，可直接 $X 读	env.X（Groovy） / $X（shell）
credentials() 注入	自动注入为 XXX_PSW、XXX_USR 等变体	$XXX_PSW（shell）

两者在 printenv 输出里没区别，都是普通环境变量。

---

七、常见坑

坑	现象	解决
printenv 输出含凭证明文	安全风险	用 grep -v 过滤 PASSWORD/SECRET/TOKEN
shell 里 $X 为空	变量没注入	确认参数名大小写、parameters 是否已生效
第一次跑看不到参数	UI 无"Build with Parameters"	先跑一次让 Jenkins 读到 parameters 定义
容器内 printenv 与节点不一致	容器内只看到注入的变量	这是正常现象，Docker agent 隔离了环境
输出太多看花眼	全量 printenv 噪音大	用白名单方式只打印自己定义的变量

---

八、总结

printenv | sort 是 Jenkins Pipeline 调试的"万能探针"------一行命令看清所有运行时变量。生产使用时建议：

1. 加过滤：屏蔽 PASSWORD/SECRET/TOKEN 等敏感字段
2. 分块输出：用户参数、自定义变量、系统变量分开
3. 归档快照 ：用 archiveArtifacts 保留每次构建的环境快照，便于事后追溯

一句话记法：

printenv | sort 一跑见真章；要安全加 grep -v，要追溯存 archiveArtifacts。

---