GitHub Actions 多行Matrix配环境变量触发Shell报错问题

API 探路者

2026-8-27

问题成因

报错核心为Shell语法错误，与续行符\识别失效无关，具体触发逻辑：

Shell变量赋值有严格语法要求：=两侧不能存在空格，若赋值内容包含空格、Shell预留特殊字符（{、[、引号等），必须将赋值内容整体用引号包裹。你的代码首行写为JSON=[ { \，=后紧跟[，随后的空格将{拆分为独立命令token，Shell会将该行解析为「临时给变量JSON赋值为[，然后执行名为{的命令」，因此直接抛出{: command not found错误，后续续行、JSON拼接逻辑完全不会执行。
即使绕过赋值错误，当前编写的JSON内容本身语法非法：tags、args数组内的字符串值未用双引号包裹，后续调用fromJSON()解析时会触发格式错误。
原写法使用::set-output时未转义换行符，长JSON文本很容易被截断，导致输出内容不完整。

解决方案

按以下步骤修正配置即可：

修正Shell赋值逻辑：用单引号整体包裹所有JSON内容（GitHub Actions的${{ }}表达式在YAML解析阶段、Shell执行前就会完成值替换，单引号不会阻断表达式渲染），删除=两侧多余空格，不需要手动加\续行符，单引号包裹的内容可以直接跨行书写。
修正JSON语法：给所有字符串值（包括tags、args数组内的每一项）包裹双引号，保证生成的内容符合标准JSON格式。
替换废弃的::set-output写法为$GITHUB_OUTPUT，同时对JSON内容中的%、换行、回车符做转义，避免长文本被截断。

修正后的生成矩阵步骤代码示例：

run: |
        JSON='[
          {
            "name": "NxMeta-LSIO Latest Develop",
            "enable": ${{ github.ref == 'refs/heads/develop' }},
            "push": ${{ github.event_name != 'pull_request' }},
            "context": "./NxMeta-LSIO",
            "tags": ["ptr727/nxmeta-lsio:develop", "ptr727/nxmeta-lsio:develop-latest", "ptr727/nxmeta-lsio:develop-${{ env.NXMETA_LATEST_VERSION }}"],
            "args": ["DOWNLOAD_VERSION=${{ env.NXMETA_LATEST_VERSION }}", "DOWNLOAD_URL=${{ env.NXMETA_LATEST_URL }}"]
          },
          {
            "name": "NxMeta-LSIO Stable Develop",
            "enable": ${{ github.ref == 'refs/heads/develop' }},
            "push": ${{ github.event_name != 'pull_request' }},
            "context": "./NxMeta-LSIO",
            "tags": ["ptr727/nxmeta-lsio:develop-stable", "ptr727/nxmeta-lsio:develop-${{ env.NXMETA_STABLE_VERSION }}"],
            "args": ["DOWNLOAD_VERSION=${{ env.NXMETA_STABLE_VERSION }}", "DOWNLOAD_URL=${{ env.NXMETA_STABLE_URL }}"]
          }
        ]'
        # 转义GITHUB_OUTPUT特殊字符，避免文本截断
        JSON="${JSON//'%'/'%25'}"
        JSON="${JSON//$'\n'/'%0A'}"
        JSON="${JSON//$'\r'/'%0D'}"
        echo "matrix=$JSON" >> $GITHUB_OUTPUT

矩阵读取部分原有逻辑无需修改，可正常解析合法JSON：

matrix:
  containers: ${{ fromJson(needs.setmatrix.outputs.matrix) }}

补充提示：如果需要过滤enable: false的构建项，建议在生成JSON数组时直接跳过对应项，不要将禁用项传入矩阵，避免生成空跑的无效任务。

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