GitHub Actions 为什么写入 GITHUB_OUTPUT 后下个步骤取不到多行值

GitHub Actions 写入 GITHUB_OUTPUT 后，下个步骤取不到多行值，通常不是 JSON 内容本身有问题，而是把多行内容当成了单行的 name=value 记录。单行写法只适合没有换行的值；JSON、测试摘要或命令返回的长文本应改用成对的多行分隔符。

官方地址：https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-commands

处理顺序是：先确认输出写成“名称 + 起始分隔符 + 内容 + 结束分隔符”，再确认生产步骤有 id，最后区分同一个 job 的 steps 引用和跨 job 的 needs 引用。

多行值为什么要单独写分隔符

GitHub Actions 的环境文件命令按行读取。把下面这种写法直接用于带换行的值，第一行可能被当成输出名和值，后续 JSON 行就不再属于同一条输出：

- name: 直接写入多行内容
  id: meta
  run: |
    # 单行写法只适用于不包含换行的值。
    echo "payload=$(> "$GITHUB_OUTPUT"

更稳妥的格式是把唯一分隔符写在值的前后。分隔符必须单独占一行，而且结束文本要和开始文本完全一致：

- name: 写入完整 JSON
  id: meta
  shell: bash
  run: |
    # 用运行编号组成边界，降低内容碰巧撞上结束标记的概率。
    delimiter="__META_${GITHUB_RUN_ID}__"
    {
      printf 'payload> "$GITHUB_OUTPUT"

如果值是完全任意的文本，官方建议不要依赖这种分隔符格式，因为内容可能单独出现同名标记。此时把内容写入文件，再用 artifact 或后续步骤的文件路径传递，边界会更清楚。本文的重点是修复 GITHUB_OUTPUT 多行写入，不是把日志重定向后当成输出变量。

下一个步骤取值时先看 id 和引用层级

生产输出的步骤必须设置 id。后续步骤通过 steps..outputs. 读取；步骤名称 name 只是展示文字，不能替代 id：

steps:
  - name: 生成元数据
    id: meta
    shell: bash
    run: |
      # 输出名 payload 必须和下方表达式保持一致。
      delimiter="__META_${GITHUB_RUN_ID}__"
      {
        printf 'payload> "$GITHUB_OUTPUT"

  - name: 消费元数据
    shell: bash
    env:
      META_JSON: ${{ steps.meta.outputs.payload }}
    run: |
      # 通过环境变量接收完整值，再交给后续脚本处理。
      printf '%s\n' "$META_JSON"

排查时按这三个字符串逐个对照：写入名是 payload，步骤 id 是 meta，表达式就是 steps.meta.outputs.payload。任意一个拼写或大小写不一致，都可能让下游看到空值。YAML 缩进也要保持在同一个 run: | 块内，不能让结束分隔符跑到脚本块外面。

跨 job 传递要再映射一次

如果消费步骤属于另一个 job，不能继续使用 steps.meta.outputs.payload，因为 steps 只表示当前 job 内的步骤。先在上游 job 的 outputs 中映射，再让下游 job 声明 needs：

jobs:
  build:
    runs-on: ubuntu-latest
    # 把步骤输出提升为 job 输出，供依赖它的 job 使用。
    outputs:
      payload: ${{ steps.meta.outputs.payload }}
    steps:
      - name: 生成元数据
        id: meta
        run: |
          # 这里省略 JSON 生成，只保留多行输出的关键格式。
          delimiter="__META_${GITHUB_RUN_ID}__"
          {
            printf 'payload> "$GITHUB_OUTPUT"

  consume:
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: 读取上游输出
        env:
          META_JSON: ${{ needs.build.outputs.payload }}
        run: |
          # 跨 job 时从 needs.job.outputs 取值。
          printf '%s\n' "$META_JSON"

这里有两层映射：steps.meta.outputs.payload 先变成 jobs.build.outputs.payload，下游再用 needs.build.outputs.payload。缺少 needs: build 时，消费 job 没有明确的依赖关系，取值也不会按预期工作。

用四个检查点确认问题已经修好

1. 看文件格式：输出名后面是 ，内容行之后有完全匹配的结束分隔符。
2. 看碰撞风险：分隔符不会在内容中单独占一行；无法保证时改用文件或 artifact。
3. 看引用层级：同一个 job 用 steps，跨 job 用 needs，并确认生产步骤确实有 id。
4. 看空值来源：把下游值临时放进环境变量并打印长度或首尾标记，不要把可能包含敏感信息的完整内容写入日志。

最小修复可以概括为：多行内容使用成对分隔符，step 输出使用稳定的 id，跨 job 时显式映射 job output。这样既能保留换行，也能把“写入失败”和“引用层级错误”区分开。

常见问题

为什么只输出了 JSON 的第一行？通常是用了单行 name=value 写法，换行后的内容没有被分隔符包住。

分隔符一定要写成 EOF 吗？不需要。可以使用任意不会单独出现在值中的标记，关键是起止文本完全一致。

同一个 job 能不能用 needs 读取步骤输出？不能。needs 用于 job 之间的依赖；同一个 job 内应使用 steps..outputs.。