Github workflow 语法

适用场景：CI/CD 自动化构建、测试、部署等
文件位置：.github/workflows/xxx.yml
语法格式：YAML（注意缩进，通常为 2 空格）

一、基本结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
name: 工作流名称（可选）

on: [触发事件] # 必需

jobs:
  job1:
    runs-on: 运行环境
    steps:
      - step1
      - step2
  job2:
    needs: job1
    runs-on: ubuntu-latest
    steps:
      - step3

二、核心字段详解

1. name（可选）

  • 定义工作流在 GitHub Actions 面板中显示的名称。

  • 示例：

    1
    name: CI Pipeline

2. on（必需）

  • 定义触发工作流的事件。
  • 常见事件：
    • push：代码推送
    • pull_request：PR 创建/更新
    • schedule：定时任务（cron）
    • workflow_dispatch：手动触发

示例

1
2
3
4
5
6
7
8
9
on:
  push:
    branches: [main, "feature/**"]
    tags: ["v*.*.*"]
  pull_request:
    branches: [main]
  schedule:
    - cron: "0 2 * * 1" # 每周一 2AM
  workflow_dispatch: # 允许手动运行

3. jobs（必需）

  • 包含一个或多个任务（job），每个 job 独立运行。
  • 可通过 needs 设置依赖关系。
1
2
3
4
5
6
7
8
jobs:
  build:
    runs-on: ubuntu-latest
    steps: [...]
  deploy:
    needs: build # 等待 build 完成
    runs-on: ubuntu-latest
    steps: [...]

4. jobs.<job>.runs-on（必需）

  • 指定 job 运行的虚拟机环境（VM）。
  • 常见值：
    • ubuntu-latest
    • windows-latest
    • macos-latest
1
runs-on: ubuntu-22.04

⚠️ 注意：每个 job 启动一台全新的 VM，结束后销毁。

5. jobs.<job>.steps（必需）

  • 每个 job 包含一系列步骤，按顺序执行。
  • 每个 step 可以是：
    • uses：使用一个 Action
    • run：执行 shell 命令

三、Step 的完整语法字段

字段 说明
name 步骤名称（推荐添加）
id 唯一标识，用于引用输出 steps.<id>.outputs
uses 使用外部或本地 Action（不能与 run 共存）
run 执行 shell 命令（Linux: bash，Windows: pwsh）
with 向 uses 的 Action 传递参数
env 设置该 step 的环境变量（局部）
if 条件判断，决定是否执行
continue-on-error true 表示出错也继续后续步骤
timeout-minutes 步骤超时时间

示例

1
2
3
4
5
6
7
8
9
- name: Build App
  id: build
  run: |
    npm install
    npm run build
  env:
    NODE_ENV: production
  if: github.ref == 'refs/heads/main'
  timeout-minutes: 10

四、关键概念解析

✅ uses：使用公共或私有 Action

  • 格式：owner/repo@version

  • 示例：

    1
    2
    3
    4
    - uses: actions/checkout@v4 # 检出代码
    - uses: actions/setup-node@v4 # 设置 Node.js
      with:
        node-version: "18"

  • 来源：

    • 公共：GitHub Marketplace（如 actions/checkout）
    • 私有：my-org/my-action@v1
    • 本地：./.github/actions/my-action

📌 actions/checkout@v4 是几乎所有 workflow 的第一步，用于拉取代码。

✅ run vs uses

类型 说明
run 执行 shell 命令（如 npm install）
uses 使用封装好的自动化模块（Action）

❌ 一个 step 不能同时使用 run 和 uses

✅ Action 的三种类型

类型 说明
JavaScript Action Node.js 编写，轻量快速（如 setup-node）
Docker 容器 Action 封装在 Docker 中，环境隔离（如 docker/build-push-action）
Composite Action YAML 定义的多个 run/uses 组合，类似“脚本集合”

✅ 环境变量与机密

1
2
3
4
5
6
7
8
9
10
11
12
13
14
env:
  GLOBAL_VAR: "global"

jobs:
  build:
    env:
      JOB_VAR: "job-level"
    steps:
      - run: echo $GLOBAL_VAR
      - run: echo $JOB_VAR
      - run: echo $STEP_VAR
        env:
          STEP_VAR: "step-only"
      - run: echo ${{ secrets.API_KEY }} # 机密信息

🔐 secrets 在仓库 Settings > Secrets 中配置。

✅ 条件控制 if

1
2
- run: npm publish
  if: github.ref == 'refs/heads/main'

常用上下文：

  • ${{ github.ref }}：当前分支
  • ${{ github.actor }}：触发者
  • ${{ secrets.X }}：机密

✅ 矩阵构建 strategy.matrix

1
2
3
4
5
6
7
8
strategy:
  matrix:
    os: [ubuntu-latest, windows-latest]
    node-version: [16, 18]
steps:
  - uses: actions/setup-node@v4
    with:
      node-version: ${{ matrix.node-version }}

五、最佳实践建议

  1. ✅ 始终使用 actions/checkout@v4 作为第一步
  2. ✅ 给每个 step 添加 name
  3. ✅ 使用 secrets 存储敏感信息
  4. ✅ 指定 Action 版本（如 @v4），避免意外更新
  5. ✅ 合理使用 if 减少不必要的执行
  6. ✅ 用 actions/cache 加速构建（如缓存 node_modules）

六、学习资源

📌 一句话总结：

Workflow = 触发事件 + 多个 Job → 每个 Job 在独立 VM 中运行 → 执行多个 Step → 每个 Step 是 Action 或 Shell 命令