CI/CD / 系统课时
从运行日志定位执行步骤
从运行日志定位执行步骤
工作流失败时,不要先猜 YAML 哪里写错,而应从一次具体的 workflow run 向下定位到 job 和 step。本篇用 Actions 页面、步骤日志与运行元数据建立固定排查顺序,让你能判断失败发生在哪一步,并拿到足够的信息继续修复。
学习目标
- 能从一次 workflow run 定位失败的 job 和 step
- 能结合步骤日志区分命令失败、环境问题和前置步骤连锁失败
- 能用运行元数据确认触发事件、提交和执行上下文
从一次运行逐层定位
GitHub Actions 的观察路径可以理解为 Workflow → Run → Job → Step → Log。一次 run 对应某次触发产生的执行记录,其中可以包含多个 job;job 再按配置执行多个 step。真正的错误通常出现在某个具体 step 的日志里。

进入仓库的 Actions 页面后,先选择对应 workflow,再打开失败的 run。运行概览能看到触发分支、提交、事件和各 job 状态。随后打开失败 job,从步骤列表中找到红色失败标记,再展开该步骤日志。
真实 GitHub 页面会随版本和仓库配置变化,因此具体按钮位置应以当前界面为准。

用日志判断第一处真实失败
排查时优先寻找第一个真正失败的步骤。后续步骤可能因为默认的成功条件没有满足而被跳过,也可能只是前一个步骤失败后的连锁结果,因此最后一个异常位置未必是根因。
例如下面的 workflow 故意执行一个不存在的脚本,可用于观察失败日志:
name: log-debug-demo
on:
workflow_dispatch:
jobs:
inspect:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Run build
run: ./scripts/build.sh
- name: Verify artifact
run: test -f dist/app.tar.gz这是配置文件示例。将它保存到 .github/workflows/log-debug-demo.yml 并手动触发后,如果仓库没有 scripts/build.sh,Run build 会失败,后面的 Verify artifact 默认不会继续执行。
预期结果
Run build: failed
Verify artifact: skipped日志中的具体 shell 错误文字、时间和退出码展示形式可能随 runner 环境变化,因此定位时关注失败步骤名称、执行命令及非零退出状态,不要依赖某一条固定日志文本。
结合运行元数据排除上下文错误
步骤本身看似正确时,再回到 run 的元数据确认它究竟在什么上下文中执行。重点检查触发事件、分支或标签、关联 commit,以及 workflow 使用的文件版本。常见情况是开发者正在查看主分支最新 YAML,却排查由旧 commit 触发的历史运行。
还要注意日志中的自动脱敏并不意味着可以主动输出 secret。不要为了调试执行 echo 打印令牌、密码或私钥;更安全的做法是验证变量是否存在、检查长度或让命令只报告认证成功与失败。
建立稳定的排查顺序
面对失败运行,可以固定按“确认 run → 找失败 job → 找第一处失败 step → 阅读该 step 的命令与错误 → 核对触发和 commit”推进。这样能够把流水线问题从一大段日志缩小到一个明确执行单元。
如果失败来自测试、构建或部署命令,日志定位只是第一阶段;拿到失败命令、退出状态和执行上下文后,再回到对应工具本身继续排查,通常比反复重跑 workflow 更有效。