GitHub Actions 怎么暂时停止日志里的命令解析

在用 GitHub Actions 跑流水线的时候，不少开发者都遇到过输出的日志内容被系统自动识别为内置命令，触发了意料之外操作的问题，想要临时关闭日志里的命令解析功能，操作起来非常简单。

你只需要在需要暂停解析的代码段前输出特殊的停止标记，后续所有日志输出都会被当成普通文本处理，直到你重新开启命令解析即可，不需要修改工作流的全局配置。

在 GitHub Actions 的脚本输出中，如果构建产物或第三方工具会打印类似 ::warning::、::error:: 的文本，可以用 stop-commands 暂时停止 workflow command 解析。做法是先生成本次运行唯一的恢复令牌，输出 ::stop-commands::令牌，原样打印需要保护的内容，最后输出完全相同的 ::令牌:: 恢复解析。

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

关键只有两点：暂停和恢复必须使用同一个令牌；令牌要足够随机且只在当前运行中使用。暂停区间只改变日志命令的解释方式，不会修改 runner 的日志文件。

先分清 stop-commands 解决的是什么

GitHub Actions 会从脚本标准输出中识别 workflow command。普通文本一旦符合命令格式，就可能被当成注释、错误或其他控制指令处理。比如下面的内容是构建工具生成的文本，并不是工作流作者想创建的 warning：

::warning::dependency metadata contains a legacy field
::error::generated report is only a sample

此时要保护的是“日志内容的解释方式”，不是删除日志、关闭步骤或改变 runner 配置。stop-commands 只适合包住一段确定的原始输出；输出完成后应尽快恢复，避免后续真正需要的 workflow command 也被当成普通文本。

从工作流运行页找到需要修改的步骤

1. 打开仓库的 Actions 页面，选择对应的 workflow run。
2. 进入产生误解析文本的 job，再展开具体的 shell 步骤。
3. 回到仓库中的工作流 YAML，在该步骤的 run: | 脚本里包住原始输出区间。

界面上应能看到一个明确的步骤边界：暂停命令写在需要保护的输出之前，恢复命令写在输出之后。不要把整个 job 都放在暂停区间里，否则后续日志中的错误标记、分组或摘要命令也不会被处理。

用唯一令牌暂停命令解析

在 Bash 步骤中，可以用 uuidgen 生成本次运行的令牌。官方语法是 ::stop-commands::{endtoken}；令牌本身要作为变量保存，后面恢复时还要原样使用：

- name: 输出构建工具的原始日志
  shell: bash
  run: |
    # 每次运行生成不同令牌，降低内容碰巧撞上恢复标记的概率。
    stop_marker="LOG_BLOCK_$(uuidgen)"
    # 从这一行开始，workflow command 不再被解释。
    echo "::stop-commands::$stop_marker"

    # 这里替换成会输出 ::warning:: 或 ::error:: 文本的命令。
    printf '%s\n' '::warning::dependency metadata contains a legacy field'
    printf '%s\n' '::error::generated report is only a sample'

    # 恢复标记必须与暂停时使用的令牌完全一致。
    echo "::$stop_marker::"

这里的恢复令牌不是固定关键字，LOG_BLOCK_ 只是便于读日志的前缀。重要的是它在本次脚本中保持不变，而且不会在被保护的文本里单独出现。若输出内容完全不可控，不能保证令牌不会出现，优先把内容写入文件并通过 artifact 或文件路径传递。

在暂停区间输出内容，恢复后再执行命令

暂停后，日志中的命令样式文本应作为普通内容显示。恢复行输出后，后续命令会重新按 workflow command 处理。下面的完整片段用一条 notice 做恢复后的对比：

- name: 控制日志命令解析范围
  shell: bash
  run: |
    # 令牌只在当前步骤内使用，避免跨步骤依赖不可见状态。
    stop_marker="LOG_BLOCK_$(uuidgen)"
    echo "::stop-commands::$stop_marker"

    # 暂停期间，这两行只作为普通日志文本输出。
    cat generated-report.txt
    printf '%s\n' '::warning::this line is intentionally plain text'

    # 恢复后，下一条 notice 才会重新进入 Actions 的命令处理。
    echo "::$stop_marker::"
    echo '::notice title=LogMode::workflow command parsing is active again'

这段写法的阅读重点是顺序：stop-commands、原始输出、同令牌恢复、恢复后的命令。不要把恢复行写成新的随机令牌，也不要遗漏两侧的双冒号；只要令牌或格式不匹配，暂停状态就不会按预期结束。

用三个可见状态验收设置

1. 暂停段：类似 ::warning:: 的文本显示在日志中，但没有新增对应的工作流注释。
2. 恢复行：日志中出现 ::令牌::，令牌与暂停行完全一致，且恢复行没有被截断或缩进到普通字符串中。
3. 恢复后：下一条明确的 ::notice 或其他 workflow command 能按正常规则处理。

如果暂停段仍然产生注释，先检查暂停命令是否真的写成 ::stop-commands::$stop_marker；如果恢复后一直没有命令生效，重点检查恢复行是否使用了同一个变量，以及 shell 是否在中途因错误退出。

常见问题

令牌可以固定写成 EOF 吗？可以使用任意不与内容冲突的标记，但固定值更容易被原始输出碰巧打印出来。每次运行生成唯一值更稳妥。

暂停命令解析会不会隐藏日志？不会。日志仍会输出，只是其中符合 workflow command 语法的文本在暂停区间不会触发对应的命令行为。

能不能只恢复某一种命令？不能把恢复令牌理解成按类型筛选的开关；恢复后是重新处理 workflow command。因此应把暂停范围缩小到真正需要保护的输出。

PowerShell 能使用同样思路吗？可以，语法仍是输出 ::stop-commands::令牌 和 ::令牌::，只是令牌生成、变量和打印命令要换成 PowerShell 写法。

最终可以把这项配置记成一条短规则：先用唯一令牌暂停，原样输出目标内容，再用同一个令牌恢复。只要暂停范围足够小，并按“暂停段—恢复行—恢复后命令”三个状态检查，日志误解析通常就能快速定位。