Jenkins对接BitBucket与Salesforce时Scratch Org创建失败问题咨询

两个异常的核心关联 #

你遇到的两个报错是因果关系：DevHub授权实际未生效是根因，创建Scratch Org时查找server.key是授权失效后的衍生问题。

问题1：授权返回成功但实际为JwtGrantError的原因 #

你的校验逻辑存在漏洞，sfdx force:auth:jwt:grant命令返回码为0仅代表命令本身执行完成，不代表授权凭证真实有效。出现JwtGrantError说明sfdx本地已经写入了DevHub的授权记录，但实际和Salesforce服务端验证连接时失败，常见原因有3个：

• 你强制设置了HOME=${env.WORKSPACE}，但Windows系统下sfdx默认读取%USERPROFILE%\.sfdx路径存储授权信息，环境变量不匹配导致授权信息写入/读取异常
• JWT授权的核心配置有误：Connected App未开IP放行、证书过期、Jenkins用户无DevHub权限集、授权用户名有误
• 你仅判断了jwt:grant命令的返回码，没有做真实连通性校验，导致授权失效的情况被忽略

问题2：创建Scratch Org时查找server.key的原因 #

sfdx执行force:org:create时需要调用DevHub的接口，检测到默认DevHub的授权状态为JwtGrantError失效后，会自动尝试复用之前JWT授权的配置重新认证，此时就会读取之前授权时记录的server.key临时路径。而Jenkins的withCredentials生成的临时密钥文件仅在块内有效，且不同Stage的临时文件路径会变化、旧文件会被自动清理，自然会报找不到server.key的错误。

解决步骤 #

1. 修正环境变量配置：Windows环境下同时指定HOME和USERPROFILE，保证sfdx读写授权路径一致

withEnv(["HOME=${env.WORKSPACE}", "USERPROFILE=${env.WORKSPACE}"]) {
  // 原有逻辑
}

2. 优化授权校验逻辑：不要仅依赖jwt命令的返回码，增加连通性校验确认授权有效，且授权失败直接终止流程，避免无效的后续步骤执行

stage('Authorize DevHub Org') {
  try {
    rc = command "sfdx force:auth:jwt:grant -r ${SF_PROD} -i ${SF_CONSUMER_KEY} -u ${SF_JENKINSUSER} -f ${server_key_file} --setdefaultdevhubusername -a ${SF_DEV_HUB}"
    if ( rc != 0 ) {
      error 'Salesforce org authorization command failed.'
    }
    // 新增连通性校验
    rc = command "sfdx force:org:display -u ${SF_DEV_HUB}"
    if ( rc != 0 ) {
      error 'DevHub connection validation failed.'
    }
    command "sfdx force:org:list"
    echo '========== LOGGED IN =========='
  }
  catch (err) {
    echo "========== DEVHUB AUTHORIZATION FAILURE: ${err} =========="
    throw err
  }           
}

3. 排查JWT授权配置

• 确认DevHub中对应Connected App已开启JWT授权，IP放松限制已配置、所用证书未过期
• 确认${SF_JENKINSUSER}对应用户已分配DevHub功能权限集，拥有创建Scratch Org的权限

4. 确认项目配置文件存在：在Create Test Scratch Org步骤前增加校验，确认config\project-scratch-def.json文件已被正常checkout到工作目录

内容的提问来源于stack exchange，提问作者Finnster