📚 课程目录第4章编写第一个Workflow

4. 编写第一个 Workflow：触发条件、简单打印日志、手动触发

GitHub Actions 的核心是 Workflow —— 一个通过 YAML 文件定义的自动化流水线。每个 Workflow 至少包含三个要素：触发条件（on）、运行环境（runs-on）和执行步骤（steps）。本章从零开始构建第一个可运行的 Workflow，覆盖最常见的触发场景与手动触发方式，并通过日志打印验证流程是否通畅。

4.1 触发事件概念与对比

Workflow 的触发条件决定了何时启动流水线。下表列出最常用的触发事件及其使用场景：

触发事件	YAML 关键字	典型用途
代码推送到分支	`push`	代码合并、推送时自动构建与测试
拉取请求	`pull_request`	PR 创建或更新时触发检查
手动触发	`workflow_dispatch`	通过 GitHub UI 或 API 手动启动工作流
定时调度	`schedule`	按 cron 表达式定期执行（如每日构建）
仓库事件	`repository_dispatch`	外部系统通过 GitHub API 触发

推荐：开发阶段优先使用 workflow_dispatch 配合 push，既保留自动触发又支持手动重跑。

4.2 实现流程：从创建到运行

在仓库根目录创建 .github/workflows/ 文件夹。
新建文件 first-workflow.yml。
编写以下 YAML 配置：

name: My First Workflow

on:
  push:
    branches:
      - main
      - develop
  workflow_dispatch:

jobs:
  print-hello:
    runs-on: ubuntu-latest
    steps:
      - name: Print greeting
        run: echo "🎉 Hello, CI/CD! 第一个工作流已成功运行。"

要点解析：on.push.branches 限制触发分支；workflow_dispatch 不附加任何参数，表示允许任何人手动触发。jobs 下定义单个任务 print-hello，运行环境为最新版 Ubuntu。steps 只包含一个 run 步骤，直接打印日志。

4.3 提交与手动触发操作

将文件提交并推送到远程仓库（确保推送的分支在 push 列表中）。
进入 GitHub 仓库 → Actions 标签页，即可看到正在运行或已完成的 Workflow。
点击 Run workflow 按钮（仅在配置了 workflow_dispatch 后出现），选择分支点击 Run workflow 手动启动。
运行完成后点击任务查看日志，应看到 🎉 Hello, CI/CD! 第一个工作流已成功运行。

常见错误：若 YAML 缩进错误（例如 jobs 前少了一个空格），GitHub 会在工作流列表显示“Invalid workflow file”。请使用 2 空格缩进，并检查冒号后是否留有空格。

4.4 手动触发与参数传递

workflow_dispatch 支持接收输入参数，方便在不改代码的情况下控制行为。以下示例添加一个可选输入 greeting_target：

on:
  workflow_dispatch:
    inputs:
      greeting_target:
        description: '问候对象'
        required: true
        default: 'World'

jobs:
  greet:
    runs-on: ubuntu-latest
    steps:
      - name: Say hello
        run: echo "Hello ${{ github.event.inputs.greeting_target }}!"

手动触发时，GitHub UI 会弹出表单要求填写 greeting_target。使用 ${{ github.event.inputs... }} 引用用户输入的值。

4.5 调试与日志分析

工作流运行后，点击具体 job 可查看实时日志。日志中的每一行都标注了步骤名和时间戳。若步骤失败，错误信息会以红色高亮显示。常见调试方法：

在 run 中添加 echo "DEBUG: ..." 输出临时变量。
使用 actions/checkout 步骤（后续章节详述）拉取代码，查看文件是否正确。
若手工触发按钮未出现，检查 workflow_dispatch 是否拼写正确（注意下划线）。

4.6 性能与稳定性基础建议

保持 Workflow 文件简洁：一个文件只做一件事，便于复用地触发条件。
使用 if 条件跳过不必要的步骤（例如仅对特定分支运行部署步骤）。
手动触发工作流不会占用任何额外配额，适合频繁调试。

4.7 常见错误排查

错误现象	可能原因	解决方案
工作流列表显示“Invalid workflow file”	YAML 缩进错误或语法错误	使用在线 YAML 校验工具检查；确保使用 2 空格缩进
手动触发按钮缺失	未添加 `workflow_dispatch` 或拼写错误	检查 `on` 下是否正确写入 `workflow_dispatch:`（注意下划线）
Job 运行后日志为空	步骤未包含任何输出命令	添加 `echo` 或 `printf` 生成输出
Job 一直处于排队状态	并发限制或资源不足	检查仓库级别的并发设置；公共仓库通常立即运行

至此，你已经成功创建并运行了第一个 Workflow。下一阶段将在此基础上引入环境变量、条件判断与多步骤流水线，使自动化更加智能。