第4节：编写第一个GitHub Actions工作流

好了，理论铺垫差不多够了。这一节我们直接动手——写你的第一个工作流。放心，真的不难。

YAML 语法速览：记住三条“铁律”

GitHub Actions 的工作流文件是用 YAML 写的。YAML 这东西吧，说白了就是给机器看的 key-value 配置，但格式要求极其严格。我个人习惯把 YAML 想象成 Python 的风格——缩进决定层级。

  • 缩进用空格，不要用 Tab —— 我至少见过三个同事因为 Tab 报错，排查了半天。
  • key 和 value 之间要有冒号+空格 —— 比如 name: my-workflow，漏了空格语法错误。
  • 列表用短横线+空格 —— 比如 - runs-on: ubuntu-latest。

💡 一个小小的技巧：把 VSCode 的「缩进检测」打开，用空格自动补齐，能省 80% 的 YAML 调试时间。

第一个工作流：Push 时打个招呼

我们从一个最简单的场景开始：当你把代码推送到 GitHub 仓库时，触发一个任务，打印一行 "Hello， GitHub Actions!"。

在仓库里新建一个文件，路径必须为：.github/workflows/hello.yml。文件名可以自定义，但目录结构是死的。

🔑 核心知识点：一个工作流文件由 name、on（触发事件）、jobs（任务）三部分组成。

name: Hello World Workflow

on:
  push:
    branches: [ main ]

jobs:
  say-hello:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Print greeting
        run: echo "Hello, GitHub Actions!"

我来解释一下每一段在干什么：

  • on.push.branches：表示只在 main 分支有 push 时触发。你也可以用 [ main, develop ] 监听多个分支。
  • jobs.say-hello：任务名叫 say-hello，你可以随意改，但建议用有意义的英文。
  • runs-on: ubuntu-latest：指定运行环境。GitHub 提供了 Ubuntu、Windows、macOS 三种。我个人大多数情况用 Ubuntu，除非要和 Windows 测试环境对接。
  • steps：每个 step 要么用 uses 调用别人写好的 action，要么用 run 执行 shell 命令。
  • actions/checkout@v4：这是官方库，作用是把你的代码拉到 runner 里。几乎所有需要访问代码的工作流第一步都会用它。

⚠️ 注意：如果你把 actions/checkout 省略了，后面的 run 命令就找不到项目文件。我曾经调试一个构建脚本半天没反应，最后发现忘了 checkout…… 这种低级错误特别容易犯。

触发场景不止 push

上面例子用了 push，但实际工作中触发方式五花八门。我整理了一张表，让你快速了解最常用的几种：

事件 写法 典型用途
推送代码 on: push 每次提交后运行测试
创建 PR on: pull_request 代码审查前自动检查
定时执行 on: schedule 比如每周一凌晨跑一次全面测试
手动触发 on: workflow_dispatch 点按钮执行，适合临时操作

你可能会问：

“如果我想在 push 和 PR 同时触发怎么办？”

很简单，写个数组就行：

on:
  push:
  pull_request:

甚至还可以加分支过滤、路径过滤，后面章节会细讲。这里先记住：on 是工作流的“入口开关”。

工作流执行流程 —— 一张图看懂

为了让你对刚才那个简单工作流有个直观印象，我画了一张流程图。它展示了从代码 push 到看到打印结果的全过程。

工作流执行流程：Push → 获取代码 → 执行命令 1. 代码 push 到 main 2. 触发 on: push 3. 启动 ubuntu-latest 4. actions/checkout@v4 5. echo 打印日志 runner 在 GitHub 云端 Actions 自动分配空闲 runner

你看，整个过程非常线性，从 push 开始到打印结束，总共 5 步。实际跑起来，你会在仓库的 Actions 页签里看到每一步的实时日志，那个体验特别爽。

踩坑实录：缩进与空格

我第一次写工作流时，直接在编辑器里按了 Tab，结果 Actions 日志直接报红：

You have an error in your yaml syntax on line 3

当时我还以为是 action 版本问题，折腾了一个小时……后来发现是缩进错了。YAML 不能用 Tab，只能用空格。而且列表的短横线后面也要有一个空格。

⚠️ 重要：建议所有 YAML 文件都用 2 个空格 做缩进。这是社区最通用的标准。不要用 4 个空格，更不要混合。我曾经接手过一份用 4 空格写的工作流，复制粘贴到别的仓库后格式全乱了。

验证你的工作流

写完 YAML 文件后，提交到 GitHub 仓库的 main 分支。然后立刻打开仓库的「Actions」页签，你会看到一条新的运行记录——

  • 如果所有步骤都变成绿色勾，恭喜你，第一个工作流成功跑通。
  • 如果出现红色叉，点击任务进去看具体日志，一般都能找到原因。

💡 一个小习惯：每次提交工作流文件前，先用 yamllint.com 在线校验一下语法。这能帮你过滤掉 90% 的缩进错误。

好啦，第一个工作流就是这样。你掌握了 YAML 三要素、触发事件的选择、以及 steps 的基本结构。接下来你就可以在这个基础上做各种有意思的事情——比如跑测试、发通知、甚至部署应用。不过那都是后话了。

现在，去写一个属于你的 hello.yml 吧。

← 上一章 📖 返回目录 下一章 →