如何正确转义CircleCI参数以在JSON字符串中使用？

问题背景 #

我封装了一个调用slack/notify的CircleCI命令，简化后代码如下：

commands:
  slack-message:
    parameters:
      message:
        type: string
    steps:
      - slack/notify:
          custom: |
            {
              "blocks": [
                {
                  "type": "section",
                  "text": {
                    "type": "mrkdwn",
                    "text": "Some additional information << parameters.message >>"
                  }
                }
              ]
            }

当message包含换行符、双引号这类特殊字符时，命令执行失败。尝试过通过run命令导出环境变量，或者在命令里加environment字段，但前者遇到双引号失效，后者直接报错：

ERROR IN CONFIG FILE:
[#/commands/slack-message] 0 subschemas matched instead of one
1. [#/commands/slack-message] expected type: String, found: Mapping
|   Command may be a string reference to another command
2. [#/commands/slack-message] extraneous key [environment] is not permitted

CircleCI配置版本为2.1，需要找到正确的解决方法。

解决方案 #

方法1：使用CircleCI内置的toJSON过滤器（推荐） #

CircleCI 2.1的模板引擎支持toJSON过滤器，它会自动将字符串转义为合法的JSON格式，处理换行符、双引号等特殊字符。修改命令如下：

commands:
  slack-message:
    parameters:
      message:
        type: string
    steps:
      - slack/notify:
          custom: |
            {
              "blocks": [
                {
                  "type": "section",
                  "text": {
                    "type": "mrkdwn",
                    "text": "Some additional information << parameters.message | toJSON >>"
                  }
                }
              ]
            }

<< parameters.message | toJSON >>会把传入的message参数自动转义，比如双引号会变成\"，换行符会变成\n，确保整个JSON结构合法，不会被特殊字符破坏。

方法2：用jq生成合法的JSON payload #

如果toJSON过滤器不符合需求，可以通过run命令调用jq工具来构建正确的JSON：

commands:
  slack-message:
    parameters:
      message:
        type: string
    steps:
      - run:
          name: Build valid Slack payload
          command: |
            # 使用jq生成包含消息的JSON，自动处理特殊字符
            SLACK_PAYLOAD=$(jq -n \
              --arg user_message "<< parameters.message >>" \
              '{
                "blocks": [
                  {
                    "type": "section",
                    "text": {
                      "type": "mrkdwn",
                      "text": "Some additional information \($user_message)"
                    }
                  }
                ]
              }')
            # 将payload导出到环境变量，供后续步骤使用
            echo "export SLACK_PAYLOAD='${SLACK_PAYLOAD}'" >> "$BASH_ENV"
      - slack/notify:
          custom: "$SLACK_PAYLOAD"

jq会严格按照JSON规范处理字符串，自动转义特殊字符，确保生成的payload格式完全合法，避免手动拼接JSON导致的语法错误。

失效原因说明 #

• 直接插入<< parameters.message >>：特殊字符会破坏JSON语法结构，导致slack/notify无法解析payload。
• 用${MESSAGE@Q}导出环境变量：仅能处理Shell层面的特殊字符，无法处理JSON层面的转义，遇到双引号依然会破坏结构。
• 在命令里加environment字段：CircleCI 2.1的commands定义不支持该键，触发配置校验错误。

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