极客工场

Appearance

共 2,516 字预计阅读约 8 分钟

Jenkins 凭据与变量找不到速查：Credentials ID、作用域与 withCredentials 用法 ​

更新时间：2026-10-24。FAQ 速查页，面向流水线日志里躺着 Credentials 'xxx' not found、或 Groovy 报 No such property 的同学。Jenkins 里「找不到一个引用」分两大族：凭据族——ID 字符串和凭据库里实际登记的 ID 对不上，或凭据建在了当前任务看不见的作用域里；变量族——withCredentials 注入的环境变量名记错、参数没定义却直接引用、Groovy 变量越作用域使用。两族报错的原文长得不一样，修法也互不相干。Jenkins 的凭据库按「域 + 文件夹 + 范围」三维组织，绝大多数「凭据找不到」不是凭据被删了，而是它建在了错误的维度上。顺一遍基本必中。如果是登录/授权层面的拦截而不是引用找不到，转 Jenkins 权限不足速查。

本文要回答的问题 ​

  • Credentials 'deploy-key' could not be found 是凭据被删了吗？
  • 明明在凭据页面能看到这条凭据，为什么流水线取不到？
  • withCredentials 里该用 credentialsId 还是凭据的「描述」？
  • No such property: PASSWORD for class: WorkflowScript 错在哪？
  • 环境变量在 environment 块里能取到，进了 sh 步骤就没了，为什么？

一、报错原文与典型现象 ​

引用类报错集中在构建日志（控制器地址以 jenkins.example.com 占位，路径以 /proj/demo 占位）：

bash
# 凭据 ID 找不到
ERROR: Credentials 'deploy-key' could not be found
# 或旧版本措辞
java.lang.RuntimeException: Credentials 'deploy-key' not found
bash
# Groovy 变量/属性未定义
org.jenkinsci.plugins.workflow.cps.CpsCompilationErrorsException:
No such property: DEPLOY_PASSWORD for class: WorkflowScript
bash
# 参数引用不存在
groovy.lang.MissingPropertyException:
No such property: params.BRANCH for class: WorkflowScript
# 凭据类型不匹配
ERROR: Credential 'deploy-key' is not of type 'Username with password'

读现象先分族：原文带 Credentials 和 ID 字符串的是凭据族，问题在 ID 拼写、作用域、范围、类型四个维度之一；No such property / MissingPropertyException 是变量族，问题在变量根本没被定义或定义在别的作用域。两族分清楚再动手。

二、病因处置速查表 ​

报错现象 / 场景可能原因快速验证处置
Credentials 'xxx' could not be foundID 字符串打错或带了空格凭据页面逐字符比对 ID 列以凭据库里的 ID 为准改 Jenkinsfile
凭据页能看到，流水线取不到凭据建在别的文件夹作用域看凭据所在文件夹与任务路径把凭据挪进任务可见的文件夹或全局域
withCredentials 取不到，节点连接能用凭据范围是 System 而非 Global凭据详情页看 Scope 字段范围改 Global，或重建为 Global
No such property: XXX变量未定义直接引用搜 Jenkinsfile 里该名字的定义点先定义再引用；或核对变量名拼写
变量在 environment 块有、sh 里没有定义在别的 stage 作用域对比两个 stage 的变量定义位置上移到外层 environment 块或显式传参
is not of type 'Username with password'凭据类型与步骤期望不符看凭据类型列与步骤文档换匹配类型的凭据，或换步骤写法
参数化构建报 params.XXX 找不到参数名写错或首次构建无参数定义看任务配置的参数列表对齐参数名；首次构建用 Build with Parameters

三、排查决策图 ​

下面这张图是标准排查路线，颜色按角色区分：红是报错入口与命中的根因，蓝是排查动作，绿是通过分支，橙是修复动作，紫是防复发沉淀。

d2
direction: down

hit: "Credentials not found\n或 No such property"
family: "分族：凭据引用\n还是变量引用"
cred: "查凭据三维：\nID 拼写 / 作用域 / 范围类型"
vars: "查变量定义点：\n是否定义 / 作用域层级"
fix: "改 ID 或挪凭据域\n补定义或上移作用域"
retest: "重跑流水线取到引用"
prevent: "凭据 ID 常量集中管理\n变量命名规范入库"

hit -> family
family -> cred: "Credentials 字样"
family -> vars: "No such property"
cred -> fix
vars -> fix
fix -> retest
retest -> prevent

hit.style: { fill: "#FDECEC"; stroke: "#D9534F" }
family.style: { fill: "#EAF2FE"; stroke: "#3B6FD4" }
cred.style: { fill: "#EAF2FE"; stroke: "#3B6FD4" }
vars.style: { fill: "#EAF2FE"; stroke: "#3B6FD4" }
fix.style: { fill: "#FEF3E2"; stroke: "#E08A1E" }
retest.style: { fill: "#E9F8F0"; stroke: "#2E9E6B" }
prevent.style: { fill: "#F1ECFD"; stroke: "#7A5BD4" }

读这张图抓分水岭：报错原文里出现 Credentials 单词走左支，按 ID → 作用域 → 范围 → 类型的顺序过四个维度；出现 No such property 走右支，问题在 Jenkinsfile 自己的变量定义与作用域，和凭据库无关。凭据族八成改配置，变量族八成改代码，不要互相用错药。

四、逐条排查展开 ​

ID 打错是凭据族的第一大病因，而且错得极有迷惑性。 Jenkinsfile 里 credentialsId: 'deploy-key' 这个字符串必须和凭据库里的 ID 逐字符一致——大小写敏感、连字符敏感、结尾空格也算不一致。很多团队的凭据是管理员在页面上手工建的，建的时候 ID 留空让系统自动生成一串随机字符，事后没人记得，文档里记的是「描述」字段，照着描述写进 Jenkinsfile 必然 not found。修法：系统管理 → Credentials 页面，找到那条凭据，点进去看 ID 列的真实值，原样抄进 Jenkinsfile。顺手把自动生成的随机 ID 改成有语义的短横线命名，全团队好记。

作用域：凭据按文件夹分层，隔壁文件夹的凭据你看不见。 Jenkins 凭据可以建在全局，也可以建在任意文件夹节点上；文件夹 /proj 下的凭据，/other 下的任务取不到——报错同样是 not found，因为对你的任务而言它确实「不存在」。典型场景：管理员把凭据建在了自己测试用的文件夹里，搬到正式任务后忘了挪。修法：把凭据建在任务所在文件夹（就近原则），或建在全局域让全站可见；多分支流水线注意凭据要建在多分支项目的父节点上。

范围（Scope）：System 范围的凭据流水线取不到。 凭据的 Scope 字段有两档：System 表示「只给 Jenkins 自身用」（典型场景是控制器连 agent 节点），Global 表示「任务和流水线可以用」。一条 System 范围的凭据，节点连接测试能通过，withCredentials 永远 not found。修法：进凭据详情页把 Scope 改成 Global；如果页面不让改，重建一条同内容、Global 范围的凭据，删掉旧的。

类型不匹配：ID 找对了，类型错了也是报错。 凭据类型有 Username with password、Secret text、SSH Username with private key、Certificate 等多种；withCredentials([usernamePassword(...)]) 期待的是 Username with password 类型，给它一个 Secret text 的 ID 就报 is not of type。修法两路：要么重建一条类型匹配的凭据，要么换用匹配现有类型的步骤写法（Secret text 对应 string(credentialsId: ..., variable: ...)，SSH 私钥对应 sshUserPrivateKey(...)）。

变量族：No such property 九成是作用域问题。 Jenkins 流水线的 environment 块定义在哪个层级，变量就活在哪个层级——定义在某个 stage 的 environment 里，出了这个 stage 就取不到；定义在 pipeline 顶层的 environment，全文可见。另一个高频错：withCredentials 的 variable: 参数决定注入的环境变量名，写的是 variable: 'DEPLOY_PW'，脚本里就得用 env.DEPLOY_PW 或在 sh 里引用同名变量，记成别的名字照样 not found。修法定一条纪律：跨 stage 要用的变量一律定义在顶层 environment 或脚本开头的 def，stage 内部环境块只放本 stage 私有的。

参数引用：params.XXX 找不到多半发生在首次构建。 声明式流水线的 parameters 块定义在 Jenkinsfile 里，但第一次跑这个任务时 Jenkins 还没加载过它，参数列表是空的，手动触发走「Build Now」不会弹参数表单，脚本里引用 params.BRANCH 直接异常。修法：参数化任务的首次构建用「Build with Parameters」跑一次让参数注册；脚本里对可选参数做防御（引用前判断存在性），别把任务跑挂。

五、规范做法与预防 ​

  • 凭据 ID 语义化：建凭据时 ID 手工指定为 团队-用途-环境 格式（如 proj-deploy-prod），禁止留空让系统生成随机串。
  • ID 常量集中管理：Jenkinsfile 顶部用 def 常量定义所有凭据 ID，全文件只引用常量，改 ID 只改一处。
  • 就近建凭据：任务在哪个文件夹，凭据建在哪个文件夹；跨文件夹共享的才放全局域，减少「看得见但取不到」。
  • Scope 默认 Global：除非明确是 Jenkins 自身用途（节点连接等），一律 Global；建完顺手在任务里跑一次验证。
  • 变量作用域最小但够用：跨 stage 变量顶层定义，stage 私有变量就地定义；withCredentials 的变量名与使用点名对点核对。
  • 首次构建走 Build with Parameters：新任务或改过 parameters 块的任务，第一次触发必须带参数表单，注册参数定义。

这一篇在知识体系里的位置 ​

本篇是 Jenkins 排错速查簇的「引用解析」入口篇：凭据取到了但权限不够看 Jenkins 权限不足速查；变量定义了但在 sh 里不展开看 Jenkins 环境变量不展开速查；凭据 ID 对但文件路径层面的引用找不到看 Jenkins 路径不存在速查；凭据和变量都对、缺的是命令本身看 Jenkins 依赖缺失速查。「报错分族 → 凭据族查四维、变量族查定义点」这条主线对一切引用类报错通用。

一句话总结 ​

Jenkins 凭据与变量找不到先按报错原文分族：带 Credentials 字样的是凭据族，按 ID 拼写（逐字符比对、别拿描述当 ID）→ 文件夹作用域（隔壁文件夹的凭据不可见）→ Scope（System 范围流水线取不到，要 Global）→ 类型匹配四维度顺一遍；No such property 是变量族，九成是 environment 块或 def 的作用域层级不对，跨 stage 变量上移到顶层，withCredentials 注入的变量名以 variable: 参数为准。参数化任务首次构建走 Build with Parameters 注册参数。凭据 ID 语义化、常量集中管理、就近建凭据三条纪律落地，这类报错基本绝迹。