Jenkins jq脚本中环境变量转义及JSON写入问题

场景说明 #

现有目标JSON文件json.xctestplan内容如下：

{
  "defaultOptions" : {
    "environmentVariableEntries" : [
      {
        "key" : "OS_VERSION",
        "value" : "13"
      }
    ]
  }
}

在Jenkins中，需要将环境变量URL插入到上述JSON的environmentVariableEntries数组中，原使用的代码如下：

sh(script: "echo \$(jq --arg url \"$URL\" '.defaultOptions.environmentVariableEntries += [{\"key\": \"URL\", \"value\": \$url}]' json.xctestplan) > json.xctestplan", returnStdout: true)

该代码存在两个问题：

1. 插入后的URL末尾会多出换行符\n
2. 当URL包含?这类特殊字符时，会抛出jq解析错误：

++ jq --arg url 'https://redacted
' '.defaultOptions.environmentVariableEntries += [{"key": "URL", "value": [$url]}]' json.xctestplan
jq: parse error: Invalid string: control characters from U+0000 through U+001F must be escaped at line 2, column 1
+ echo

解决方案 #

问题1：去除URL末尾的换行符 #

Jenkins中环境变量可能会带有换行符，先通过trim()方法去除：

def trimmedURL = URL.trim()

问题2：避免特殊字符解析错误 & 修正jq语法 #

原代码中错误地将$url用[]包裹，导致语法错误；同时直接在shell中拼接变量容易出现转义问题，改用Jenkins双引号字符串插值+正确jq语法，通过--arg安全传递变量（--arg会自动处理特殊字符转义）。

另外，避免echo $(...) > file的写法，这种方式可能引入额外换行，直接让jq输出到文件更可靠（可用jq -i参数原地修改文件，或用临时文件替换原文件）。

修正后的完整代码 #

def trimmedURL = URL.trim()
sh(script: """
  jq --arg url "${trimmedURL}" '.defaultOptions.environmentVariableEntries += [{"key": "URL", "value": \$url}]' json.xctestplan > temp.xctestplan && mv temp.xctestplan json.xctestplan
""", returnStdout: true)

或者使用jq的原地修改参数（需jq 1.5+版本支持）：

def trimmedURL = URL.trim()
sh(script: "jq --arg url \"${trimmedURL}\" '.defaultOptions.environmentVariableEntries += [{\"key\": \"URL\", \"value\": \$url}]' -i json.xctestplan", returnStdout: true)

说明 #

• trim()方法确保URL变量不含末尾换行符，解决第一个问题
• --arg传递变量时，jq会自动处理URL中的特殊字符（如?、&等），避免解析错误
• 用临时文件替换原文件（或jq -i原地修改），避免echo引入的额外换行或文件写入问题

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