Jenkins Pipeline带参数REST API触发构建参数未识别？正确调用方法

核心问题定位 #

你当前请求中的JSON参数结构完全不符合Jenkins REST API的规范，是参数无法被识别的首要原因。
Jenkins在解析buildWithParameters接口传入的JSON格式参数时，要求参数数组的每个元素必须包含固定的name（参数名）和value（参数值）两个键，你当前的写法直接把参数名作为对象键，缺少固定结构字段，会导致Jenkins完全跳过这部分参数解析，最终仅使用任务配置的默认参数值。

错误与正确结构对比 #

你当前使用的错误参数结构：

{"parameter": [{"PARAM1": "true"},{"PARAM2": "foo"},{"PARAM3": "X.X.X.X"}]}

符合规范的正确JSON结构：

{"parameter": [
  {"name": "PARAM1", "value": "true"},
  {"name": "PARAM2", "value": "foo"},
  {"name": "PARAM3", "value": "X.X.X.X"}
]}

可直接复用的正确触发命令 #

兼容标准JSON格式的命令 #

修正参数结构后，对应可正常生效的curl命令如下：

curl -k -X POST \
  "https://<Jenkins URL>/job/<my job name>/buildWithParameters?token=XXXXXXXXXXXXXX" \
  --user <user>:<API_TOKEN> \
  --data-urlencode json='{"parameter": [{"name":"PARAM1","value":"true"},{"name":"PARAM2","value":"foo"},{"name":"PARAM3","value":"X.X.X.X"}]}'

更易调试的非JSON传参方式 #

Jenkins buildWithParameters 接口原生支持直接通过POST表单字段传递参数，无需强制组装JSON结构，可大幅降低转义出错概率，示例命令：

curl -k -X POST \
  "https://<Jenkins URL>/job/<my job name>/buildWithParameters?token=XXXXXXXXXXXXXX" \
  --user <user>:<API_TOKEN> \
  --data-urlencode PARAM1=true \
  --data-urlencode PARAM2=foo \
  --data-urlencode PARAM3=X.X.X.X

两种传参方式效果完全等价，日常测试推荐使用第二种，无需额外处理JSON转义问题 #

环境相关排查项 #

如果修正参数结构后仍存在参数不生效问题，可结合你当前的部署环境按以下顺序排查：

• Apache反向代理配置问题：检查代理配置，确保无截断POST请求体、无强制改写请求头的规则，需完整传递Content-Type、Content-Length头信息，避免请求参数被代理层过滤
• Pipeline参数定义匹配问题：确认任务中配置的参数名和传递的参数名完全一致，无大小写偏差、无拼写错误，参数类型与传递值兼容（如布尔型参数不要传入无法被解析的特殊字符串）
• 重复字段覆盖问题：如果使用直接表单传参方式，不要额外携带json字段，否则可能出现两类参数逻辑冲突、后传入值覆盖前值的问题
• 版本兼容性确认：Jenkins 2.210版本对上述两种传参方式均原生支持，无需额外安装参数传递类插件

注意：API Token、任务身份校验token可同时生效，不会造成参数读取逻辑异常

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