在 Jenkins Pipeline 里处理凭据，我一般先想清楚两件事：这个凭据该在哪个构建步骤出现，以及它会不会被日志带走。下面从基本用法开始，逐步说作用域、泄露防线和 PR 场景。

基本写法：用 withCredentials 绑定到块内环境变量

在Jenkins Pipeline中，推荐使用withCredentials步骤将凭据绑定为环境变量。假设有一个secret text凭据，其ID是my-secret，可以这样写：withCredentials([string(credentialsId: 'my-secret', variable: 'MY_SECRET')]) { ... }。在花括号内的步骤中，通过$MY_SECRET或env.MY_SECRET引用即可。如果是在sh脚本中执行，直接使用$MY_SECRET。需要特别注意的是，不要用echo $MY_SECRET输出值，否则会直接打印到构建日志中，造成凭据泄露。这是最常见的错误之一，也是每次构建时读取凭据的推荐方式。

这里有一个容易被忽略的边界：withCredentials 块内的变量只在块内有效。如果你有几个相邻步骤都需要同一个凭据，就把它们都放进同一个块里，不要先存到字符串变量再带出去，因为那样你可能不小心写进环境或者日志。对于 usernamePassword 类型的凭据，绑定后会产生两个变量：usernameVariable 和 passwordVariable，在 Linux shell 里用 $MY_USER 和 $MY_PASSWORD，在 Windows 批处理里用 %MY_USER% 和 %MY_PASSWORD%。变量名别和构建自带的环境变量撞名，否则后定义的会覆盖。

作用域和节点可见性：先确认凭据能传到 Agent

凭据作用域的选择会影响Pipeline在Agent节点上的可用性。Jenkins中的系统凭据只对当前节点上的构建可见，全局凭据则对所有项目可见。当Pipeline运行在Agent节点时，系统凭据可能不会被传输到该节点，导致引用时变量为空。检查方法：在节点上执行一个简单的构建步骤，尝试读取该凭据并只打印变量名（不要打印值）。如果变量为空或构建报错提示找不到凭据，说明作用域不匹配或凭据ID错误。建议优先使用全局凭据，除非确实需要多租户隔离。

实际操作时，我会先在 Jenkins 的“凭据”页面确认 ID 是否拼对、有没有被删掉。经常遇到的情况是：凭据存在 Jenkins Master 上，但 Pipeline 跑的 Agent 是另一个容器或虚拟机，这时系统凭据不会跟随过去。用全局凭据虽然方便，但要注意访问控制，如果你有多个不相关的项目共用同一个 Jenkins，最好用文件夹级别的凭据并给对应 Pipeline 授权，而不是把所有项目都堆在全局。检查时可以在 Agent 上跑一个临时任务，只输出变量是否存在：

withCredentials([string(credentialsId: 'my-secret', variable: 'MY_SECRET')]) {
    sh 'test -n "$MY_SECRET" && echo "defined" || echo "undefined"'
}

泄露比写错更常见：几个容易忽略的地方

常见的凭据泄露陷阱包括：在环境块中提前注入凭据、将凭据作为命令行参数传给第三方工具、在sh步骤中未关闭命令回显。例如，不要写environment { MY_SECRET = credentials('my-secret') }，因为这样会在整个构建过程中全局暴露，且继续传递时容易进入日志。对于sh步骤，可以在脚本前添加set +x来隐藏命令回显，避免凭据被打印。构建结束后，应手动检查日志中是否出现凭据片段，如果出现则立即轮换该凭据并修正Pipeline脚本。

我的经验是，凭据泄露很少是因为 Jenkins 的加密机制被破解，更多是自己把值打印出来了。比如在调试时习惯性地 echo 一下，或者把凭据拼到 URL 里传给 curl。如果你要在命令行里使用，可以先把凭据写进一个临时文件，然后用 @ 参数引用，用完立刻删除。

多分支与 PR：高权限凭据要收着点

多分支 Pipeline 里，来自 fork 的 Pull Request 是最需要警惕的。不要给 PR 构建自动注入管理员级或生产环境的凭据，因为你不知道提交者会不会在脚本里塞一段偷数据的代码。我一般这样判断：如果 env.CHANGE_ID 存在且来源是 fork，就只注入只读凭据，或者把需要敏感凭据的步骤直接跳过。如果只跑在主分支上，才放开完整权限。

另外，如果构建报错找不到凭据，先不要盲目重试。检查顺序是：凭据 ID 是否写错、凭据是否已删除、作用域是否匹配当前节点、Pipeline 是否运行在正确的环境。Jenkins 对不存在的凭据通常会报类似 “No credentials found” 的错误，对作用域不匹配可能只是变量为空，所以要结合日志看。

构建后检查与回滚边界

构建结束后，建议花一分钟在 Console 输出里搜索凭据明文的片段。如果发现泄露，不要只改脚本，还要立即在 Jenkins 里轮换该凭据，因为旧值可能已经被抓走。回滚边界要清楚：如果你只是改脚本，凭据本身没变，风险还在；只有轮换之后才算真正止血。

还有一个很多人忽略的点：凭据轮换后，要重新触发一次构建来确认新值能正常使用。不要用旧凭据的 build 日志去验证，因为日志里可能混着两种值。先清空旧的构建记录，或者换一个新的构建号，这样更干净。