GitHub Actions 入门：YAML 工作流基础与触发器配置

说实话，第一次看到 .github/workflows 文件夹里的 YAML 文件时，我有点懵。一堆缩进、冒号、还有那几个看不懂的关键字——on、jobs、runs-on。这是啥？能吃吗？

后来项目越来越多，每次推送代码都要手动跑测试、手动部署，折腾几次就觉得烦了。那时候才意识到：GitHub Actions 这东西，真能省不少事儿。

这篇文章就是想聊聊 GitHub Actions 的基础——YAML 工作流怎么写、触发器怎么配。不讲那些花里胡哨的高级功能，就说最实用、最常用的部分。看完能上手，这才是关键。

---

GitHub Actions 能帮你干啥

简单说，就是自动化。

以前我们推送代码后得手动做一堆事：跑测试、检查代码格式、构建项目、部署到服务器。现在把这些步骤写成 YAML 文件，GitHub 帮你自动执行。

举个例子：你每次推送代码到 main 分支，GitHub Actions 自动帮你跑测试。测试通过了才允许合并 PR。这样一来，代码质量有保障，你也省心。

还有个好处：免费。公开仓库完全免费，私有仓库每月也有 2000 分钟的免费额度（对于个人项目绰绰有余）。

---

YAML 工作流长啥样

先看个最简单的例子：

name: 测试工作流

on: push

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: 打印问候
        run: echo "Hello, GitHub Actions!"

逐行拆解：

name：工作流的名字。随便取，方便在 GitHub Actions 页面识别。

on：触发条件。这里写 push，意思是每次推送代码都触发这个工作流。

jobs：任务块。一个工作流可以包含多个 job（任务），它们可以并行或串行执行。

build：这个 job 的 ID。随便命名，但建议有意义（比如 build、test、deploy）。

runs-on：运行环境。ubuntu-latest 表示在最新的 Ubuntu 服务器上跑。还可以选 windows-latest、macos-latest。

steps：步骤列表。一个 job 由多个 step 组成，按顺序执行。

run：执行的命令。这里就是打印一句话。

这就是最基础的骨架。后面复杂的工作流，无非就是在这个基础上堆更多 job、更多 step、更多判断逻辑。但别慌，先把基础搞明白，复杂的自然就懂了。

---

触发器：让工作流知道什么时候跑

触发器（trigger）是整个工作流的”开关”。配置对了，工作流才会在合适的时机跑起来。

常用的触发器有四种：push、pull_request、schedule、workflow_dispatch。咱们一个一个聊。

1. push：代码推送时触发

最常用的触发器。

on: push

这样写，每次推送代码到任意分支都会触发。

但通常我们只想在特定分支触发：

on:
  push:
    branches:
      - main
      - dev

这段配置的意思：只有推送到 main 或 dev 分支时才触发。其他分支？不管。

还能更精细——只监听特定路径的改动：

on:
  push:
    branches:
      - main
    paths:
      - 'src/**'
      - 'package.json'

只有 src/ 目录下的文件或 package.json 变了才触发。这样改文档或配置文件时不会白白跑一遍 CI。

2. pull_request：PR 相关操作触发

PR（Pull Request）是团队协作的核心场景。

on: pull_request

这样写，PR 的所有操作都会触发：打开 PR、更新 PR、重新打开 PR。

但同样可以限定分支：

on:
  pull_request:
    branches:
      - main

只有目标分支是 main 的 PR 才触发。

还能指定 PR 的操作类型：

on:
  pull_request:
    types:
      - opened
      - synchronize
      - reopened

• opened：PR 刚打开时
• synchronize：PR 有新的提交（比如你推送了新改动）
• reopened：关闭的 PR 重新打开

这个配置挺常见——PR 打开时跑测试，确保改动没问题。

3. schedule：定时触发

像定时任务一样，按计划跑工作流。

on:
  schedule:
    - cron: '0 0 * * *'

这是 cron 表达式，格式：分 时 日 月 星期。

上面那行意思是：每天 UTC 时间 0 点（北京时间早上 8 点）跑一次。

常用场景：每天自动跑测试、定期清理缓存、定时生成报告。

说实话，cron 表达式挺容易写错。有几个在线工具可以帮你验证，比如 crontab.guru。

4. workflow_dispatch：手动触发

有时候我们需要手动触发——比如一键部署、手动跑某个特定任务。

on: workflow_dispatch

配置后，GitHub Actions 页面会出现一个 “Run workflow” 按钮。点击就能手动触发。

还能配置输入参数：

on:
  workflow_dispatch:
    inputs:
      environment:
        description: '部署环境'
        required: true
        default: 'production'
        type: choice
        options:
          - production
          - staging

手动触发时可以选择部署到哪个环境。这样一键部署到测试或生产环境都行。方便吧？

组合触发器

实际项目中往往需要多个触发器：

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main
  schedule:
    - cron: '0 6 * * 1'  # 每周一早上 6 点 UTC
  workflow_dispatch:

这段配置的意思：

• 推送到 main 分支时触发
• 目标分支是 main 的 PR 触发
• 每周一早上跑一次
• 支持手动触发

一个工作流，多种触发方式。挺常见的配置模式。

---

实战：给 Node.js 项目配个自动测试

咱们来写个实用的例子——Node.js 项目自动跑测试。

假设你的项目结构是这样的：

my-project/
├── src/
├── tests/
├── package.json
└── .github/
    └── workflows/
        └── test.yml

创建 .github/workflows/test.yml 文件：

name: 自动测试

on:
  push:
    branches:
      - main
      - dev
  pull_request:
    branches:
      - main

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      # 1. 检出代码
      - name: 检出代码
        uses: actions/checkout@v4

      # 2. 安装 Node.js
      - name: 设置 Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      # 3. 安装依赖
      - name: 安装依赖
        run: npm ci

      # 4. 运行测试
      - name: 运行测试
        run: npm test

      # 5. 代码格式检查（可选）
      - name: 检查代码格式
        run: npm run lint

逐个步骤解释：

检出代码：actions/checkout@v4 是官方提供的 Action，把你的代码仓库下载到运行环境中。

设置 Node.js：actions/setup-node@v4 也是官方 Action，安装指定版本的 Node.js。node-version: '20' 表示用 Node.js 20。

安装依赖：npm ci 比 npm install 更适合 CI 环境——它严格按照 package-lock.json 安装，更快更可靠。

运行测试：直接跑你的测试命令。前提是 package.json 里配置了 test 脚本。

代码格式检查：如果你配置了 ESLint 或 Prettier，这一步能自动检查代码格式。

这个工作流会在推送到 main 或 dev 分支时触发，也会在目标分支是 main 的 PR 触发。这样每次改动都有测试把关。

---

常见踩坑点

说实话，我刚开始写 YAML 时踩过不少坑。这里列几个常见的：

1. 缩进错误

YAML 对缩进极其敏感。必须用空格，不能用 Tab。缩进层级必须一致。

# ❌ 错误：缩进不一致
jobs:
build:
  runs-on: ubuntu-latest

# ✅ 正确：统一缩进
jobs:
  build:
    runs-on: ubuntu-latest

建议用编辑器的 YAML 插件，会自动高亮缩进错误。

2. 触发器不生效

有时候配置了触发器但工作流不跑。常见原因：

• 分支配置错了：比如你推送到 develop 分支，但配置只监听 main
• fork 的仓库：从 fork 仓库推送不会触发 push 事件的工作流
• PR 来自 fork：来自 fork 的 PR 默认不会触发某些触发器

3. 忘记检出代码

新手最容易犯的错误：忘了用 actions/checkout@v4。

没有这一步，工作流环境里是空的——你的代码根本不在里面。

steps:
  # ❌ 错误：直接运行命令，但代码还没检出
  - run: npm test

  # ✅ 正确：先检出代码
  - uses: actions/checkout@v4
  - run: npm test

4. Action 版本太老

有些教程用 actions/checkout@v2 或 v3。但建议用最新版本 v4，功能更完善，性能更好。

定期检查你用的 Action 有没有新版本。GitHub 会提醒你版本过时。

---

一些实用建议

触发器选择原则

问自己几个问题：

• 想自动跑还是手动跑？ → 自动用 push/pull_request，手动用 workflow_dispatch
• 跑的频率高吗？ → 频率高就限定分支或路径，避免浪费资源
• 团队协作吗？ → PR 场景必配 pull_request

性能优化小技巧

• 限定触发范围：只监听关键分支和路径
• 并行执行：多个独立的 job 可以并行跑
• 利用缓存：actions/setup-node 会自动缓存 Node.js 和依赖，不用每次重装

命名要清晰

# ❌ 模糊命名
jobs:
  job1:
    steps:
      - name: step1

# ✅ 清晰命名
jobs:
  test:
    steps:
      - name: 安装依赖

清晰的名字方便排查问题——GitHub Actions 页面会显示每个 step 的名字。

---

推荐的学习路径

这篇文章只讲了基础。如果你想深入，可以继续学：

1. 矩阵构建：同时在多个环境（Node.js 16、18、20）跑测试
2. 缓存优化：手动配置缓存，加快构建速度
3. Secret 管理：安全存储 API Key、密码等敏感信息
4. 自定义 Action：封装自己的 Action，复用逻辑
5. 部署自动化：自动部署到服务器或云平台

官方文档是最好的资源：GitHub Actions 文档。内容很全，就是有点长。

还有个建议：多看别人的配置。GitHub 上很多开源项目的 .github/workflows 文件夹都有完整配置，直接抄作业也行。

---

最后聊两句

说了这么多，其实核心就三件事：

1. YAML 结构：name、on、jobs、steps 四个关键字搭骨架
2. 触发器配置：push、pull_request、schedule、workflow_dispatch 四种最常用
3. 实战案例：Node.js 自动测试是最典型的入门场景

我还记得写好第一个工作流后的那种感觉——推送代码，GitHub 自动帮我跑测试，然后给我发邮件说”测试通过了”。那种”一切都在掌控中”的踏实感，真的挺爽。

后面想学更高级的功能（矩阵构建、缓存优化、部署自动化），基础打好了也不难。GitHub Actions 这东西，入门门槛不高，但用好真能省不少时间。至少不用每次推送代码都手动跑测试了，对吧？

配置 GitHub Actions 自动测试工作流

为 Node.js 项目创建自动化测试工作流，实现推送代码时自动运行测试

⏱️ 预计耗时: 15 分钟

1. 1

   步骤1: 创建工作流文件

   在项目根目录创建 .github/workflows/test.yml 文件：
   
   • 路径必须精确：.github/workflows/
   • 文件名建议有意义：test.yml、ci.yml
   • 文件后缀必须是 .yml 或 .yaml
2. 2

   步骤2: 配置触发器

   设置工作流触发条件：
   
   • push 触发：监听 main、dev 分支
   • pull_request 触发：监听目标分支为 main 的 PR
   • 支持限定路径：paths: ['src/**']
3. 3

   步骤3: 配置运行环境

   指定运行环境和 Node.js 版本：
   
   • runs-on: ubuntu-latest（最新 Ubuntu）
   • uses: actions/setup-node@v4
   • node-version: '20'（Node.js 20）
4. 4

   步骤4: 编写测试步骤

   按顺序执行测试流程：
   
   • 检出代码：uses: actions/checkout@v4
   • 安装依赖：run: npm ci（推荐用 ci 而非 install）
   • 运行测试：run: npm test
   • 格式检查：run: npm run lint（可选）
5. 5

   步骤5: 验证工作流

   推送代码后检查运行结果：
   
   • 在 GitHub Actions 页面查看运行状态
   • 检查每个 step 的日志输出
   • 确认测试通过后再合并 PR

常见问题

GitHub Actions 和其他 CI/CD 工具（如 Jenkins）有什么区别？

GitHub Actions 内置在 GitHub 里，配置更简单，适合 GitHub 项目。Jenkins 功能更强大但需要独立部署和维护。对于个人项目和小团队，GitHub Actions 更方便上手。

YAML 文件必须放在 .github/workflows 目录吗？

是的，路径必须精确。GitHub 只会识别 .github/workflows/ 目录下的 YAML 文件作为工作流配置。放在其他位置不会被执行。

为什么我的工作流推送到分支后没有触发？

常见原因：1）分支配置错误（推送的分支不在监听列表）；2）仓库是 fork（fork 仓库的 push 事件默认不触发）；3）路径限定（改动文件不在监听路径）。检查这几项基本能找到问题。

npm ci 和 npm install 有什么区别？

npm ci（Clean Install）严格按照 package-lock.json 安装，更快更可靠，适合 CI 环境。npm install 会尝试解决版本冲突，可能产生不一致的结果。自动化测试建议用 npm ci。

私有仓库的 GitHub Actions 有费用吗？

私有仓库每月有 2000 分钟免费额度（MacOS 环境 10 分钟）。超出后按用量计费：Linux 0.008 美元/分钟，Windows 0.016 美元/分钟，MacOS 0.08 美元/分钟。个人项目通常够用。

如何避免每次推送都触发工作流？

限定触发范围：1）只监听关键分支（branches: [main]）；2）只监听关键路径（paths: ['src/**']）；3）组合使用，比如只在 main 分支的 src/ 目录改动时触发。

---

参考资料

• GitHub Actions 官方文档
• Workflow Syntax for GitHub Actions
• Events that trigger workflows
• 阮一峰 GitHub Actions 入门教程

10 分钟阅读 · 发布于: 2026年4月5日 · 修改于: 2026年4月5日