Github Actions使用方法

Github Actions使用方法

1 GitHub Actions 的基本概念

  • 在 GitHub Actions 中，工作流（workflow）由多个任务（job）组成，每个任务包含一系列步骤（step）。核心概念如下：

  • Workflow（工作流）：定义自动化流程的 YAML 配置文件，存放在 .github/workflows/ 目录下。

  • Job（任务）：一个完整的执行单元，可以包含多个步骤。

  • Step（步骤）：任务中的具体执行操作，比如拉取代码、安装依赖、运行脚本等。

  • Runner（运行器）：执行 GitHub Actions 任务的服务器，分为 GitHub 提供的托管 runner 和自托管 runner。

  • Event（触发事件）：定义何时运行工作流，例如 push、pull_request、schedule（定时任务）等。

2 解释

工作流文件件存在于你的仓库.github/workflows目录下的*.yml

2.1 示例代码

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

name: CI Workflow  # 工作流名称

on: 
  push:            # 触发条件：当代码被推送到仓库时触发
    branches:
      - main       # 仅当推送到 main 分支时触发
  pull_request:    # 触发条件：当有 PR 时触发

jobs:
  test:            # 定义一个名为 "test" 的任务
    runs-on: ubuntu-latest  # 运行环境，使用 GitHub 提供的 Ubuntu 最新版本
    steps:
      - name: Checkout Code   # 第一步：拉取代码
        uses: actions/checkout@v4

      - name: Setup Node.js    # 第二步：设置 Node.js 环境
        uses: actions/setup-node@v4
        with:
          node-version: 18

      - name: Install Dependencies  # 第三步：安装项目依赖
        run: npm install

      - name: Run Tests  # 第四步：执行测试
        run: npm test

3 触发条件

触发方式 说明
push 代码推送时触发
pull_request PR 相关操作时触发
workflow_dispatch 手动触发
schedule 定时运行
repository_dispatch 通过 Webhook 触发
workflow_call 允许其他工作流调用

3.1 push（推送触发）

  • 示例 1：所有推送都会触发
    1
    on: push
    表示任何 git push 操作都会触发工作流。
  • 示例 2：指定分支触发
    1
    2
    3
    4
    5
    on:
      push:
        branches:
          - main
          - dev
    只有当代码推送到 main 或 dev 分支时才会触发。
  • 示例 3：指定路径触发
    1
    2
    3
    4
    5
    on:
      push:
        paths:
          -'src/**'
          - '!src/ignore-file.txt'
    只有 src/ 目录下的文件变更时才会触发，但 src/ignore-file.txt 为例外。

3.2 pull_request（拉取请求触发）

  • 示例 1：默认触发
    1
    on: pull_request
    表示在所有分支上的 PR 操作（opened、synchronize、reopened）都会触发。
  • 示例 2：指定分支触发
    1
    2
    3
    4
    on:
      pull_request:
        branches:
          - main
    仅当 PR 目标分支是 main 时触发。
  • 示例 3：指定 PR 事件触发
    1
    2
    3
    4
    5
    6
    on:
      pull_request:
        types:
          - opened      # PR 创建时触发
          - synchronize # PR 更新时触发（新提交）
          - reopened    # 重新打开 PR 时触发
    可以选择特定 PR 事件来触发工作流。

3.3 workflow_dispatch（手动触发）

  • 示例 1：支持手动触发
    1
    2
    on:
      workflow_dispatch:
    添加此配置后，可以在 GitHub “Actions” 页面手动运行工作流。
  • 示例 2：手动触发并传入参数
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    on:
      workflow_dispatch:
        inputs:
          environment:
            description: "选择运行环境"
            required: true
            default: "production"
            type: choice
            options:
              - development
              - staging
              - production
    触发时可以选择 development、staging 或 production 作为运行环境。

3.4 schedule（定时任务触发）

1
2
3
4
5
6
7
8
   cron语法
┌───────── 分钟（0 - 59）
│ ┌────────── 小时（0 - 23）
│ │ ┌─────────── 日期（1 - 31）
│ │ │ ┌──────────── 月份（1 - 12）
│ │ │ │ ┌───────────── 星期（0 - 7，0 和 7 都代表星期天）
│ │ │ │ │
*  *  *  *  *
  • 示例 1：每天凌晨 12 点运行
    1
    2
    3
    on:
      schedule:
        - cron: '0 0 * * *'
    GitHub Actions 服务器使用 UTC 时间，如果需要北京时间（UTC+8），需要调整为 cron: ‘0 16 * * *’。
  • 示例 2：每 6 小时运行一次
    1
    2
    3
    on:
      schedule:
        - cron: '0 */6 * * *'
  • 示例 3：每周一上午 8 点运行
    1
    2
    3
    on:
      schedule:
        - cron: '0 8 * * 1'
    表示每周一（1 代表周一）北京时间 8:00 运行。

3.5 repository_dispatch（Webhook 事件触发）

  • 示例：监听外部 Webhook 事件
    1
    2
    3
    on:
      repository_dispatch:
        types: [custom-event]
    然后使用 GitHub API 触发：
    1
    2
    3
    4
    curl -X POST -H "Authorization: token YOUR_GITHUB_TOKEN" \
         -H "Accept: application/vnd.github.v3+json" \
         "https://api.github.com/repos/USERNAME/REPO/dispatches" \
         -d '{{"event_type": "custom-event"}}'
    这样，你可以从外部应用（如 Jenkins、GitLab CI）触发 GitHub Actions。

3.6 workflow_call（被其他工作流调用）

  • 示例：定义可复用的工作流
    在 reusable-workflow.yml 文件中：
    1
    2
    on:
      workflow_call:
    在另一个工作流中调用：
    1
    2
    3
    jobs:
      call-reusable-workflow:
        uses: user/repo/.github/workflows/reusable-workflow.yml@main
    这样就可以实现工作流复用。

3.7 push 和 pull_request 组合触发

1
2
3
4
5
6
7
on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main

这样，当推送到 main 分支或 PR 目标分支为 main 时，工作流都会执行。

3.8 多种触发方式结合

1
2
3
4
5
6
7
8
9
10
on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main
  workflow_dispatch:
  schedule:
    - cron: '0 16 * * *'

这表示：

  • 当代码推送到 main 分支时触发
  • 当 PR 目标分支为 main 时触发
  • 可以手动触发
  • 每天 UTC 时间 16:00 触发（对应北京时间 00:00）

4 Job的结构

4.1 Job 的完整结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
jobs:
  job_name:             # 任务 ID（唯一标识）
    name: 任务名称       # 任务的可读名称（可选）
    runs-on: 运行环境   # 任务运行的环境
    needs: 依赖任务     # 当前任务需要等待哪些任务完成（可选）
    if: 条件判断        # 任务是否执行的条件（可选）
    outputs:            # 任务的输出变量（可选）
      key: value
    strategy:           # 并行或矩阵策略（可选）
      matrix: ...
    steps:              # 任务中的执行步骤
      - name: 步骤名称
        id: 步骤 ID
        uses: 使用 GitHub 组件
        run: 执行 Shell 命令
        with: 组件的参数
        env: 设定环境变量

4.2 Job 各字段详细说明

4.2.1 job_name（任务 ID）

job_name是 GitHub Actions 内部唯一标识该任务的 ID，不能重复。

• 只能使用小写字母、数字、-或_。

• 不能有空格。

• 这个 ID 可用于依赖（needs）、输出变量（outputs）。

示例

1
2
3
4
5
jobs:
  build_project:   # 任务 ID
    runs-on: ubuntu-latest
    steps:
      - run: echo "运行 build_project"

4.2.2 name（任务名称）

name是任务的可读名称，它会在 GitHub Actions 界面中显示。

• 可以包含空格、大小写、特殊字符。

• 不影响 ID，完全是为了可读性。

示例

1
2
3
4
5
6
jobs:
  build:
    name: 📦 构建项目  # 任务名称
    runs-on: ubuntu-latest
    steps:
      - run: echo "运行 Build 任务"

👉GitHub Actions 界面会显示📦构建项目，但 job ID 仍然是build。

4.2.3 runs-on（运行环境）

指定 job 运行在哪个操作系统或环境上。可以选择：

• GitHub 托管环境：

• ubuntu-latest（默认）

• windows-latest

• macos-latest

• 指定特定版本：

• ubuntu-20.04

• windows-2022

• 自定义 Runner：

• self-hosted

示例

1
2
3
4
5
jobs:
  test:
    runs-on: ubuntu-22.04  # 在 Ubuntu 22.04 运行
    steps:
      - run: echo "运行测试"

4.2.4 needs（依赖任务）

用于让 job 依赖其他 job 的执行结果，必须等前置 job 成功后才运行。

示例

1
2
3
4
5
6
7
8
9
10
11
jobs:
  job1:
    runs-on: ubuntu-latest
    steps:
      - run: echo "Job 1 完成"

  job2:
    needs: job1  # 只有 job1 成功后才会运行
    runs-on: ubuntu-latest
    steps:
      - run: echo "Job 2 开始"

• job1先执行。

• job2依赖job1，等job1成功后才会运行。

4.2.5 if（条件判断）

用于控制 job 是否执行，可以结合状态检查、分支、标签等条件。

示例 1：仅在 main 分支执行

1
2
3
4
5
6
jobs:
  deploy:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - run: echo "仅在 main 分支执行"

示例 2：只有 job1 成功时运行

1
2
3
4
5
6
7
8
9
10
11
12
jobs:
  job1:
    runs-on: ubuntu-latest
    steps:
      - run: exit 0  # 成功

  job2:
    needs: job1
    if: success()  # 只有 job1 成功才执行
    runs-on: ubuntu-latest
    steps:
      - run: echo "Job 1 成功，继续执行 Job 2"

👉其他if关键字：

• success()：前置 job 成功时执行。

• failure()：前置 job 失败时执行。

• always()：无论前置 job 成功或失败都会执行。

4.2.6 outputs（任务输出）

用于让当前 job 生成的值被其他 job 读取。

示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
jobs:
  job1:
    runs-on: ubuntu-latest
    outputs:
      message: ${{ steps.step1.outputs.result }}  # 任务的输出
    steps:
      - id: step1
        run: echo "result=hello world" >> $GITHUB_ENV  # 生成变量

  job2:
    needs: job1
    runs-on: ubuntu-latest
    steps:
      - run: echo "Job 1 的输出是 ${{ needs.job1.outputs.message }}"

• job1生成message="hello world"。

• job2读取job1的outputs并打印。

4.2.7 strategy（并行策略）

strategy.matrix可以让 job 在多个环境下同时运行，适用于不同版本测试。

示例

1
2
3
4
5
6
7
8
9
10
11
jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [14, 16, 18]  # 在 3 个 Node.js 版本上运行
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
      - run: echo "测试 Node.js 版本 ${{ matrix.node-version }}"

👉执行结果：GitHub Actions 会自动创建 3 个任务，分别在 Node.js 14、16 和 18 运行。

4.2.8 steps（任务的执行步骤）

steps是 job 内部的执行单元，每个 step 运行一个命令或 GitHub 组件。

示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
jobs:
  my_job:
    runs-on: ubuntu-latest
    steps:
      - name: 拉取代码
        uses: actions/checkout@v4

      - name: 运行 Shell 命令
        run: echo "Hello World!"

      - name: 设置环境变量
        env:
          MY_VAR: "test"
        run: echo "环境变量是 $MY_VAR"

👉steps关键字段：

• name：步骤名称（可选）。

• uses：使用 GitHub 官方组件。

• run：执行 Shell 命令。

• env：设置环境变量。

• with：传递参数给uses。

5 Runs-on相关

5.1 runs-on语法结构

1
2
3
4
5
jobs:
  job_name:
    runs-on: 运行环境
    steps:
      - run: echo "Hello World!"

runs-on指定任务运行的操作系统。可选值包括：ubuntu-latest、windows-latest、macos-latest等。

5.2 GitHub 托管 Runner

GitHub 提供的虚拟机运行 job，无需配置服务器。支持三种操作系统：

操作系统 关键字
Ubuntu（默认） ubuntu-latest
Windows windows-latest
macOS macos-latest

5.2.1 Ubuntu

Ubuntu 是默认 Runner，启动最快，支持最多工具。

1
runs-on: ubuntu-latest

可选版本：

• ubuntu-22.04

• ubuntu-20.04（推荐）

• ubuntu-18.04（即将废弃）

示例

1
2
3
4
5
jobs:
  test:
    runs-on: ubuntu-20.04
    steps:
      - run: echo "运行 Ubuntu 20.04"

5.2.2 Windows

适用于 Windows 相关的构建和测试。

1
runs-on: windows-latest

可选版本：

• windows-2022

• windows-2019（推荐）

示例

1
2
3
4
5
jobs:
  test:
    runs-on: windows-2019
    steps:
      - run: echo "Windows 任务"

5.2.3 macOS

适用于 macOS/iOS 开发，如 Xcode、Swift。

1
runs-on: macos-latest

可选版本：

• macos-14

• macos-13

• macos-12（推荐）

示例

1
2
3
4
5
jobs:
  test:
    runs-on: macos-12
    steps:
      - run: echo "Mac 任务"

5.2.4 自托管 Runner

如果官方 Runner 不满足需求（如 ARM 设备、私有服务器），可以自建 Runner。

1
runs-on: self-hosted

可以加标签：

1
runs-on: [self-hosted, linux, arm64]

示例

1
2
3
4
5
jobs:
  my_job:
    runs-on: [self-hosted, ubuntu, gpu]
    steps:
      - run: echo "自托管 Runner"

👉适用场景：

• 运行 ARM 设备（如树莓派）

• 需要访问私有网络资源

• 需要更强的硬件性能

5.3 组合多个runs-on

5.3.1 标签实现多个runs-on

可以同时指定多个标签，让 job 运行在符合所有条件的 Runner 上。

示例

1
runs-on: [self-hosted, ubuntu, docker]

仅在自托管且 Ubuntu 并支持 Docker 的 Runner 上执行。

5.3.2 runs-on动态选择（矩阵matrix）

可以使用矩阵strategy.matrix在不同环境同时运行 job。

示例

1
2
3
4
5
6
7
8
jobs:
  test:
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
    runs-on: ${{ matrix.os }}
    steps:
      - run: echo "运行在 ${{ matrix.os }}"

👉这个 job 会自动运行 3 次，分别在：

  1. ubuntu-latest

  2. windows-latest

  3. macos-latest

5.4 runs-on的完整示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
jobs:
  job1:
    runs-on: ubuntu-latest
    steps:
      - run: echo "运行在 Ubuntu"

  job2:
    runs-on: windows-2019
    steps:
      - run: echo "运行在 Windows"

  job3:
    runs-on: macos-12
    steps:
      - run: echo "运行在 macOS"

  job4:
    runs-on: [self-hosted, gpu]
    steps:
      - run: echo "运行在自托管 GPU 服务器"

6 steps

6.1 steps语法结构

1
2
3
4
5
6
7
8
9
10
11
jobs:
  job_name:
    runs-on: ubuntu-latest
    steps:
      - name: 步骤名称（可选）
        id: 步骤 ID（可选）
        uses: GitHub 组件（可选）
        run: 执行 Shell 命令（可选）
        with: 传递参数（仅用于 `uses`）
        env: 设定环境变量（可选）
        if: 条件判断（可选）

• name：步骤名称，在 GitHub Actions UI 显示。

• id：步骤唯一标识，用于引用该步骤的输出。

• uses：使用 GitHub 官方/社区组件。

• run：执行 Shell 命令（如果不使用uses）。

• with：传递参数给uses。

• env：环境变量。

• if：设置步骤执行条件。

6.2 steps关键字段解析

6.2.1 name（步骤名称）

name是 GitHub Actions UI 中的步骤名称，用于标记当前步骤的作用。

示例

1
2
3
steps:
  - name: 🚀 运行 Shell 命令
    run: echo "Hello, GitHub Actions!"

👉运行效果：

1
2
🚀 运行 Shell 命令
Hello, GitHub Actions!

❗注意：name只是 UI 显示，不影响步骤执行。

6.2.2 id（步骤 ID）

id用于在当前job内唯一标识某个步骤，可以让后续步骤读取它的输出。

示例

1
2
3
4
5
6
7
steps:
  - name: 计算时间
    id: time_step
    run: echo "time=$(date +%s)" >> $GITHUB_ENV

  - name: 读取时间
    run: echo "时间戳是 ${{ env.time }}"

👉解析：

• id: time_step标记该步骤。

• echo "time=$(date +%s)" >> $GITHUB_ENV保存输出变量。

• run: echo "时间戳是 ${{ env.time }}"读取前一个步骤的变量。

6.2.3 uses（使用 GitHub 组件）

GitHub Actions 允许直接使用社区组件，避免重复造轮子。

组件来源：

• GitHub 官方：actions/checkout@v4

• 第三方社区：actions/setup-node@v4

示例 1：使用checkout组件拉取代码

1
2
3
steps:
  - name: 拉取代码
    uses: actions/checkout@v4

示例 2：使用setup-node组件安装 Node.js

1
2
3
4
5
steps:
  - name: 安装 Node.js 16
    uses: actions/setup-node@v4
    with:
      node-version: 16

👉解析：

• uses: actions/setup-node@v4使用官方setup-node组件。

• with.node-version: 16安装 Node.js 16。

6.2.4 run（运行 Shell 命令）

run直接执行 Shell 命令，支持 Linux（Bash）、Windows（PowerShell）。

示例 1：单行命令

1
2
3
steps:
  - name: 运行 Bash 命令
    run: echo "Hello, GitHub Actions!"

示例 2：多行命令

1
2
3
4
5
6
steps:
  - name: 多行 Shell 命令
    run: |
      echo "第一行"
      echo "第二行"
      echo "第三行"

示例 3：Windows 执行 PowerShell

1
2
3
4
steps:
  - name: 运行 PowerShell
    run: Write-Output "Hello, Windows!"
    shell: pwsh

6.2.5 with（传递参数）

用于给uses组件传递参数，不同的组件with参数不同。

示例 1：使用setup-node安装 Node.js

1
2
3
4
5
steps:
  - name: 使用 `setup-node` 安装 Node.js
    uses: actions/setup-node@v4
    with:
      node-version: 18

👉解析：

• with.node-version: 18指定安装 Node.js 18。

示例 2：上传文件

1
2
3
4
5
6
steps:
  - name: 上传文件
    uses: actions/upload-artifact@v3
    with:
      name: my-artifact
      path: ./output

• with.name指定上传的文件名称。

• with.path指定上传的文件夹路径。

6.2.6 env（环境变量）

用于设置步骤的环境变量，可以让run读取。

示例 1：自定义环境变量

1
2
3
4
5
steps:
  - name: 设置环境变量
    env:
      GREETING: "Hello"
    run: echo "$GREETING, GitHub Actions!"

👉解析：

• env.GREETING: "Hello"定义变量。

• echo "$GREETING, GitHub Actions!"使用变量。

示例 2：使用 GitHub 内置环境变量

1
2
3
steps:
  - name: 显示 GitHub 仓库信息
    run: echo "当前仓库：${{ github.repository }}"

GitHub 提供了内置变量，如：

• ${{ github.repository }}：当前仓库名。

• ${{ github.ref }}：当前分支。

• ${{ github.actor }}：触发者。

6.2.7 if（条件执行）

if用于控制步骤是否执行，支持：

• 成功时执行：if: success()

• 失败时执行：if: failure()

• 始终执行：if: always()

• 按分支执行：if: github.ref == 'refs/heads/main'

示例 1：仅在 main 分支执行

1
2
3
4
steps:
  - name: 仅在 main 分支执行
    if: github.ref == 'refs/heads/main'
    run: echo "当前是 main 分支"

示例 2：前面步骤失败时执行

1
2
3
4
5
6
7
steps:
  - name: 运行失败的命令
    run: exit 1

  - name: 失败时运行
    if: failure()
    run: echo "上一步失败了！"

6.3 steps组合示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
jobs:
  my_job:
    runs-on: ubuntu-latest
    steps:
      - name: 拉取代码
        uses: actions/checkout@v4

      - name: 设置环境变量
        env:
          MY_VAR: "Hello"
        run: echo "$MY_VAR, GitHub Actions!"

      - name: 安装 Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 18

      - name: 运行 npm 脚本
        run: npm install && npm test

      - name: 仅在 main 分支执行部署
        if: github.ref == 'refs/heads/main'
        run: echo "部署到生产环境"

GitHub Actions 中的strategy详解

strategy用于控制job的执行方式，可以用于：

• 并行执行多个任务（矩阵matrix）

• 重试失败的任务（fail-fast和max-parallel）

7 strategy相关

7.1 strategy语法结构

1
2
3
4
5
6
7
8
9
10
jobs:
  job_name:
    runs-on: ubuntu-latest
    strategy:
      matrix: # 定义矩阵
        变量名称: [值1, 值2, 值3]
      fail-fast: true  # 其中一个失败，全部取消
      max-parallel: 2  # 最多同时运行 2 个任务
    steps:
      - run: echo "Hello World"

7.2 matrix（矩阵构建）

matrix允许并行运行多个job，每个job使用不同的参数组合。

示例 1：在不同操作系统运行

1
2
3
4
5
6
7
8
jobs:
  test:
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
    runs-on: ${{ matrix.os }}
    steps:
      - run: echo "当前系统是 ${{ matrix.os }}"

👉这个job会自动运行 3 次：

  1. ubuntu-latest

  2. windows-latest

  3. macos-latest

示例 2：在不同 Node.js 版本运行

1
2
3
4
5
6
7
8
9
10
11
12
jobs:
  test:
    strategy:
      matrix:
        node: [14, 16, 18]
    runs-on: ubuntu-latest
    steps:
      - name: 设置 Node.js
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}
      - run: node -v

👉这个job会运行 3 次：

• 使用 Node.js 14

• 使用 Node.js 16

• 使用 Node.js 18

7.3 组合多个matrix变量

可以组合多个变量，GitHub Actions 会自动生成所有可能的组合。

示例

1
2
3
4
5
6
7
8
9
jobs:
  test:
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest]
        node: [14, 16]
    runs-on: ${{ matrix.os }}
    steps:
      - run: echo "系统: ${{ matrix.os }}, Node.js 版本: ${{ matrix.node }}"

👉自动生成 4 组job：

os node
ubuntu-latest 14
ubuntu-latest 16
windows-latest 14
windows-latest 16

7.4 exclude（排除某些组合）

有时不需要所有组合，可以排除一些组合。

示例

1
2
3
4
5
6
7
8
9
10
11
12
jobs:
  test:
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest]
        node: [14, 16]
      exclude:
        - os: windows-latest
          node: 14  # 排除 Windows + Node 14
    runs-on: ${{ matrix.os }}
    steps:
      - run: echo "系统: ${{ matrix.os }}, Node.js 版本: ${{ matrix.node }}"

👉只运行 3 组job：

os node
ubuntu-latest 14
ubuntu-latest 16
windows-latest 16

7.5 include（添加额外组合）

可以手动添加额外的matrix组合。

示例

1
2
3
4
5
6
7
8
9
10
11
12
jobs:
  test:
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest]
        node: [14, 16]
      include:
        - os: ubuntu-latest
          node: 18  # 额外增加 Ubuntu + Node 18
    runs-on: ${{ matrix.os }}
    steps:
      - run: echo "系统: ${{ matrix.os }}, Node.js 版本: ${{ matrix.node }}"

👉生成 5 组job：

os node
ubuntu-latest 14
ubuntu-latest 16
ubuntu-latest 18
windows-latest 14
windows-latest 16

7.6 fail-fast（任务失败时是否取消）

fail-fast: true（默认）：如果有一个job失败，取消所有剩余任务

fail-fast: false：即使有任务失败，其他job仍然运行

示例

1
2
3
4
5
6
7
8
9
jobs:
  test:
    strategy:
      fail-fast: false  # 允许所有任务运行完
      matrix:
        os: [ubuntu-latest, windows-latest]
    runs-on: ${{ matrix.os }}
    steps:
      - run: exit 1  # 故意让任务失败

👉fail-fast: false时，失败的任务不影响其他任务。

7.7 max-parallel（最大并行任务数）

默认：GitHub Actions 会并行执行所有matrix任务

可以限制最大并行任务数

示例

1
2
3
4
5
6
7
8
9
jobs:
  test:
    strategy:
      max-parallel: 2  # 同时最多运行 2 个任务
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
    runs-on: ${{ matrix.os }}
    steps:
      - run: echo "当前系统: ${{ matrix.os }}"

👉3 个任务会最多 2 个同时运行，1 个等待。

7.8 strategy组合示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest]
        node: [14, 16, 18]
      exclude:
        - os: windows-latest
          node: 14  # 排除 Windows + Node 14
      include:
        - os: ubuntu-latest
          node: 20  # 额外增加 Ubuntu + Node 20
      fail-fast: false  # 任务失败时继续执行
      max-parallel: 2  # 最多同时运行 2 个任务
    runs-on: ${{ matrix.os }}
    steps:
      - name: 安装 Node.js
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}
      - run: node -v

👉执行的任务：

os node
ubuntu-latest 14
ubuntu-latest 16
ubuntu-latest 18
ubuntu-latest 20
windows-latest 16
windows-latest 18

8 env 变量

8.1 env变量的三种作用域

env变量可以在以下三种层级定义：

  1. 工作流级别（workflow）：适用于整个.yml文件

  2. 任务级别（job）：适用于 job 内所有 steps

  3. 步骤级别（step）：仅适用于单个 step

8.2 env语法结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
name: 示例工作流
on: push

env: # ✅ 工作流级变量（全局）
  GLOBAL_VAR: "全局变量"

jobs:
  my_job:
    runs-on: ubuntu-latest
    env: # ✅ `job` 级变量（适用于 `my_job`）
      JOB_VAR: "任务变量"
    steps:
      - name: 显示全局变量
        run: echo "$GLOBAL_VAR"

      - name: 显示任务变量
        run: echo "$JOB_VAR"

      - name: 设置步骤变量
        env: # ✅ `step` 级变量（仅适用于本 `step`）
          STEP_VAR: "步骤变量"
        run: echo "$STEP_VAR"

执行结果：

1
2
3
全局变量
任务变量
步骤变量

8.3 env变量的作用范围

作用域 关键字 影响范围
工作流级 env: 适用于整个 .yml 文件
任务级 jobs.<job_name>.env: 适用于 job 内所有 steps
步骤级 jobs.<job_name>.steps[].env: 仅适用于该 step

8.4 使用env变量

8.4.1 读取环境变量

在run里使用不同的 Shell 读取env变量：

操作系统 Shell 读取方法
Linux/macOS Bash $VAR_NAME
Windows PowerShell $env:VAR_NAME
Windows CMD %VAR_NAME%

示例：

1
2
3
4
5
6
7
8
9
10
11
jobs:
  example:
    runs-on: ubuntu-latest
    env:
      MESSAGE: "Hello from job"
    steps:
      - name: 读取环境变量（Linux/macOS）
        run: echo "$MESSAGE"
      - name: 读取环境变量（Windows）
        run: Write-Output $env:MESSAGE
        shell: pwsh

输出：

1
2
Hello from job
Hello from job

8.4.2 组合多个变量

示例：

1
2
3
4
5
6
7
8
9
jobs:
  example:
    runs-on: ubuntu-latest
    env:
      USER_NAME: "Alice"
      GREETING: "Hello"
    steps:
      - name: 使用多个变量
        run: echo "$GREETING, $USER_NAME!"

输出：

1
Hello, Alice!

8.5 env变量的高级用法

8.5.1 GITHUB_ENV（动态设置env变量）

可以在run中动态创建env变量。

示例：

1
2
3
4
5
6
7
8
jobs:
  example:
    runs-on: ubuntu-latest
    steps:
      - name: 设置环境变量
        run: echo "MY_VAR=动态变量" >> $GITHUB_ENV
      - name: 读取环境变量
        run: echo "$MY_VAR"

输出：

1
动态变量

8.5.2 读取 GitHub 内置环境变量

GitHub 提供了许多内置变量，可以直接在env里使用。

示例：

1
2
3
4
5
6
jobs:
  example:
    runs-on: ubuntu-latest
    steps:
      - name: 显示 GitHub 内置变量
        run: echo "当前仓库: ${{ github.repository }}"

可能输出：

1
当前仓库: my-user/my-repo

常见 GitHub 内置变量：

变量 作用
${{ github.repository }} 仓库名 (owner/repo)
${{ github.ref }} 触发的分支/标签
${{ github.event_name }} 触发事件 (push, pull_request)
${{ github.actor }} 触发工作流的用户
${{ github.run_id }} 运行 ID（唯一）

8.5.3 secrets（私密变量）

secrets用于存储敏感数据（如 API 密钥），不会暴露在日志里。

示例：

1
2
3
4
5
6
jobs:
  example:
    runs-on: ubuntu-latest
    steps:
      - name: 读取 GitHub 密钥
        run: echo "TOKEN = ${{ secrets.MY_SECRET }}"

如何添加secrets：

  1. 进入 GitHub 仓库Settings

  2. 打开Secrets and variables→选择Actions

  3. 点击New repository secret

  4. 添加MY_SECRET，值为my_secret_value

8.5.4 env变量 vssecrets

类型 适用场景 是否加密 是否可在 UI 查看
env 普通环境变量 ❌ 否 ✅ 可以
secrets 敏感信息（API 密钥） ✅ 是 ❌ 不可

####8.6 env变量的常见问题

❓1.为什么env变量在run里无效？

正确写法：

1
2
3
4
5
steps:
  - name: 读取 `env`
    env:
      MESSAGE: "Hello"
    run: echo "$MESSAGE"

错误写法：

1
2
3
steps:
  - name: 变量未定义
    run: echo "$MESSAGE"  # 变量未在 `env` 定义

修正：

1
2
3
4
5
steps:
  - name: 先定义变量
    run: echo "MESSAGE=Hello" >> $GITHUB_ENV
  - name: 读取变量
    run: echo "$MESSAGE"

❓2.secrets变量为什么在日志里不显示？

GitHub 自动隐藏secrets变量，即使你echo也不会显示。

示例：

1
2
3
4
5
6
jobs:
  example:
    runs-on: ubuntu-latest
    steps:
      - name: 读取密钥
        run: echo "TOKEN=${{ secrets.MY_SECRET }}"

错误输出：

1
TOKEN=***

正确输出：

1
TOKEN=your_actual_secret_value  （但不会显示在 GitHub UI）

9 uses语法

uses语法过多自行访问GitHub Marketplace查找