CI/CD / 系统课时
打开调试日志追踪异常
打开调试日志追踪异常
当普通 Actions 日志只显示 Process completed with exit code 1,却看不出变量、表达式或 Runner 在哪里出错时,需要逐层增加可观测信息。本节用 GitHub Actions 的调试日志、步骤输出和临时诊断命令,把失败范围缩小到具体步骤和运行环境。
学习目标
- 理解 Runner 与 Step 调试日志分别解决什么问题
- 使用调试变量和步骤级诊断信息定位失败位置
- 在获得证据后关闭高噪声调试并清理临时输出
先从失败步骤开始
不要一看到失败就打开所有调试选项。先展开失败 Job,找到第一个真正失败的 Step,并阅读它之前的输出。后续步骤因 if: success() 没有执行,通常只是前一个错误的结果。
对于脚本步骤,可以先让 Shell 显示正在执行的命令,并输出少量不会泄露凭据的环境信息。下面的诊断步骤适用于 Ubuntu Runner。
name: debug-example
on:
workflow_dispatch:
jobs:
diagnose:
runs-on: ubuntu-latest
steps:
- name: Inspect runtime
shell: bash
run: |
set -euxo pipefail
echo "runner_os=$RUNNER_OS"
echo "workspace=$GITHUB_WORKSPACE"
pwd
git --version预期输出
runner_os=Linux
workspace=<PATH>
<PATH>
git version <VERSION><PATH> 和 <VERSION> 会随 Runner 与仓库变化。set -x 会把执行的命令展开到日志,因此不要在包含密码、Token 或其他敏感值的脚本中无条件启用它。
打开 Actions 调试日志
GitHub Actions 支持两个常用诊断变量:ACTIONS_RUNNER_DEBUG 用于增加 Runner 诊断日志,ACTIONS_STEP_DEBUG 用于增加步骤级调试输出。可在仓库或组织的 Actions secrets/variables 中按 GitHub 当前支持的方式设置为 true,然后重新运行失败工作流。
步骤调试更适合观察 Action 或步骤执行细节;Runner 调试则适合排查 Runner 执行环境、任务调度和 Runner 侧异常。定位完成后应恢复原设置,避免长期产生大量日志。

用临时诊断信息验证假设
详细日志仍然可能只告诉你“哪里失败”,而不能直接解释“为什么失败”。此时应围绕假设增加最小诊断信息。例如怀疑工作目录或构建产物不存在,可以检查当前目录和目标文件,而不是一次输出整个环境。
- name: Diagnose artifact
shell: bash
run: |
echo "cwd=$(pwd)"
test -d dist || { echo "dist directory is missing"; exit 1; }
find dist -maxdepth 2 -type f -print预期结果:存在 dist 时输出其中的文件路径;不存在时输出以下信息并以非零状态结束。
dist directory is missing这种诊断方式比直接执行 env、递归打印整个工作区更安全,也更容易从日志中找到真正相关的信息。
注意日志中的敏感信息
GitHub 会对已识别的 secret 做日志遮罩,但这不意味着任意派生值、编码后的凭据或程序自行拼接的数据都一定安全。调试时不要打印 Token、私钥、云凭据和完整请求头,也不要为了排错关闭应用自身的安全处理。
排查的目标不是制造最多日志,而是逐步增加能验证当前假设的信息。先锁定失败 Step,再按需开启 Step 或 Runner 调试,最后用最小诊断命令验证路径、文件和运行环境;根因确认后删除临时输出并关闭调试设置。