Jenkins Credentials 插件不自动注入凭据到环境变量，必须用 withCredentials 块显式绑定并在闭包内使用；secret text、username/password、SSH key 等类型语法不同，且作用域、ID 大小写、插件兼容性均需严格匹配。

Jenkins 的 Credentials 插件不是“配个密码就完事”的开关，它默认不自动注入到 shell 环境，也不兼容所有插件调用方式——直接写 env.PASSWORD 或 $PASSWORD 几乎肯定失败。

为什么 pipeline 里读不到你存的 credentials？

Credentials 插件本身不把凭据塞进环境变量，除非你显式声明。Jenkins Pipeline 的沙箱机制还会拦截未授权的凭据访问，哪怕你在界面上选中了 secret text，没用 withCredentials 块包裹，sh 步骤里根本看不到它。

• Secret text 类型的凭据不会自动映射为环境变量名，必须用 credentialsId + variable 显式绑定
• Username with password 类型会拆成两个变量（USERNAME 和 PASSWORD），但仅在 withCredentials 内有效
• Groovy 脚本里不能用 env.MY_SECRET 直接读取，必须通过 withCredentials 回调参数或 credentials() DSL 获取
• 旧版 freestyle job 若没勾选 “Use Jenkins Credentials”，即使配置了 credentials binding，也不会生效

Pipeline 中安全注入 credentials 的标准写法

只有一种可靠路径：用 withCredentials 将凭据绑定为临时变量，在闭包内使用。它支持多种凭据类型，但语法细节差异大。

• Secret text：

  withCredentials([string(credentialsId: 'my-api-token', variable: 'API_TOKEN')]) {
    sh 'curl -H "Authorization: Bearer $API_TOKEN" https://api.example.com/deploy'
  }

• Username/password：

  withCredentials([usernamePassword(
      credentialsId: 'ssh-deploy-user',
      usernameVariable: 'DEPLOY_USER',
      passwordVariable: 'DEPLOY_PASS'
  )]) {
    sh 'ssh $DEPLOY_USER@host "echo deployed"'
  }

• SSH key（推荐用于 git clone 或 rsync）：

  withCredentials([sshUserPrivateKey(
      credentialsId: 'git-deploy-key',
      keyFileVariable: 'IDENTITY_FILE',
      usernameVariable: 'GIT_USER'
  )]) {
    sh 'GIT_SSH_COMMAND="ssh -i $IDENTITY_FILE -o StrictHostKeyChecking=no" git clone git@github.com:org/repo.git'
  }

常见踩坑点：权限、作用域和插件兼容性

凭据泄露往往不出现在代码里，而出现在日志、环境泄漏或错误的作用域中。

• withCredentials 外部的 sh 步骤无法访问绑定变量，连 echo $API_TOKEN 都是空——这不是 bug，是设计
• 若 pipeline 使用 script 块并手动调用 env.API_TOKEN，会返回 null；必须在 withCredentials 闭包内用 Groovy 变量（如 API_TOKEN）而非 env.API_TOKEN
• 某些插件（如 Docker Build and Publish）有自己的 credentials 字段，填错 ID 或选错类型会导致认证失败，且错误日志常只显示 “unauthorized”，不提示凭据来源问题
• 凭据 ID 区分大小写，复制时多一个空格或换行就会匹配失败；建议在 Credentials 页面点“复制 ID”按钮，别手敲

最易被忽略的是凭据的 scope 设置：Global（全局）凭据可被所有 job 访问，但一旦误删就全挂；Folder 级凭据更安全，但跨文件夹调用需显式开启继承，否则 pipeline 找不到 credentialsId。