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 示例代码


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 事件触发

on:
  pull_request:
    types:
      - opened      # PR 创建时触发
      - synchronize # PR 更新时触发（新提交）
      - reopened    # 重新打开 PR 时触发

可以选择特定 PR 事件来触发工作流。

3.3 workflow_dispatch（手动触发）

示例 1：支持手动触发
1
2
on:
workflow_dispatch:
添加此配置后，可以在 GitHub “Actions” 页面手动运行工作流。

示例 2：手动触发并传入参数

on:
  workflow_dispatch:
    inputs:
      environment:
        description: "选择运行环境"
        required: true
        default: "production"
        type: choice
        options:
          - development
          - staging
          - production

触发时可以选择 development、staging 或 production 作为运行环境。

3.4 schedule（定时任务触发）

   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 触发：

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 组合触发

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

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

3.8 多种触发方式结合

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 的完整结构

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）。

示例

jobs:
  build_project:   # 任务 ID
    runs-on: ubuntu-latest
    steps:
      - run: echo "运行 build_project"

4.2.2 name（任务名称）

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

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

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

示例

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

示例

jobs:
  test:
    runs-on: ubuntu-22.04  # 在 Ubuntu 22.04 运行
    steps:
      - run: echo "运行测试"

4.2.4 needs（依赖任务）

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

示例

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 分支执行

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

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

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 读取。

示例

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 在多个环境下同时运行，适用于不同版本测试。

示例

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 组件。

示例

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`语法结构

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（即将废弃）

示例

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（推荐）

示例

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（推荐）

示例

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]

示例

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。

示例

jobs:
  test:
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
    runs-on: ${{ matrix.os }}
    steps:
      - run: echo "运行在 ${{ matrix.os }}"

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

ubuntu-latest
windows-latest
macos-latest

5.4 `runs-on`的完整示例

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`语法结构

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内唯一标识某个步骤，可以让后续步骤读取它的输出。

示例

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

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：多行命令

steps:
  - name: 多行 Shell 命令
    run: |
      echo "第一行"
      echo "第二行"
      echo "第三行"

示例 3：Windows 执行 PowerShell

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

6.2.5 `with`（传递参数）

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

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

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

👉解析：

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

示例 2：上传文件

steps:
  - name: 上传文件
    uses: actions/upload-artifact@v3
    with:
      name: my-artifact
      path: ./output

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

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

6.2.6 `env`（环境变量）

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

示例 1：自定义环境变量

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 分支执行

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

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

steps:
  - name: 运行失败的命令
    run: exit 1

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

6.3 `steps`组合示例

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`语法结构

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：在不同操作系统运行

jobs:
  test:
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
    runs-on: ${{ matrix.os }}
    steps:
      - run: echo "当前系统是 ${{ matrix.os }}"

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

ubuntu-latest
windows-latest
macos-latest

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

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 会自动生成所有可能的组合。

示例

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`（排除某些组合）

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

示例

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组合。

示例

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仍然运行

示例

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任务

可以限制最大并行任务数

示例

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`组合示例

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变量可以在以下三种层级定义：

工作流级别（workflow）：适用于整个.yml文件
任务级别（job）：适用于 job 内所有 steps
步骤级别（step）：仅适用于单个 step

8.2 `env`语法结构

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%`

示例：

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 组合多个变量

示例：

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变量。

示例：

jobs:
  example:
    runs-on: ubuntu-latest
    steps:
      - name: 设置环境变量
        run: echo "MY_VAR=动态变量" >> $GITHUB_ENV
      - name: 读取环境变量
        run: echo "$MY_VAR"

输出：

动态变量

8.5.2 读取 GitHub 内置环境变量

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

示例：

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 密钥），不会暴露在日志里。

示例：

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

如何添加secrets：

进入 GitHub 仓库Settings
打开Secrets and variables→选择Actions
点击New repository secret
添加MY_SECRET，值为my_secret_value

8.5.4 `env`变量 vs`secrets`

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

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

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

正确写法：

steps:
  - name: 读取 `env`
    env:
      MESSAGE: "Hello"
    run: echo "$MESSAGE"

错误写法：

1
2
3

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

修正：

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

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

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

示例：

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

错误输出：

TOKEN=***

正确输出：

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

9 `uses`语法

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

官方文档

更具体的请看官方文档吧！如果上面内容有有错误欢迎指出！

GitHub Actions 文档

本文采用署名-非商业性使用-相同方式共享 4.0 国际许可协议，转载请注明出处。

Github Actions 超详细教程，看这一篇就够了！

1 GitHub Actions 的基本概念

2 解释

2.1 示例代码

3 触发条件

3.1 push（推送触发）

3.2 pull_request（拉取请求触发）

3.3 workflow_dispatch（手动触发）

3.4 schedule（定时任务触发）

3.5 repository_dispatch（Webhook 事件触发）

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

3.7 push 和 pull_request 组合触发

3.8 多种触发方式结合

4 Job的结构

4.1 Job 的完整结构

4.2 Job 各字段详细说明

4.2.1 job_name（任务 ID）

4.2.2 name（任务名称）

4.2.3 runs-on（运行环境）

4.2.4 needs（依赖任务）

4.2.5 if（条件判断）

4.2.6 outputs（任务输出）

4.2.7 strategy（并行策略）

4.2.8 steps（任务的执行步骤）

5 Runs-on相关

5.1 runs-on语法结构

5.2 GitHub 托管 Runner

5.2.1 Ubuntu

5.2.2 Windows

5.2.3 macOS

5.2.4 自托管 Runner

5.3 组合多个runs-on

5.3.1 标签实现多个runs-on

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

5.4 runs-on的完整示例

6 steps

6.1 steps语法结构

6.2 steps关键字段解析

6.2.1 name（步骤名称）

6.2.2 id（步骤 ID）

6.2.3 uses（使用 GitHub 组件）

6.2.4 run（运行 Shell 命令）

6.2.5 with（传递参数）

6.2.6 env（环境变量）

6.2.7 if（条件执行）

6.3 steps组合示例

7 strategy相关

7.1 strategy语法结构

7.2 matrix（矩阵构建）

7.3 组合多个matrix变量

7.4 exclude（排除某些组合）

7.5 include（添加额外组合）

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

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

7.8 strategy组合示例

8 env 变量

8.1 env变量的三种作用域

8.2 env语法结构

8.3 env变量的作用范围

8.4 使用env变量

8.4.1 读取环境变量

8.4.2 组合多个变量

8.5 env变量的高级用法

8.5.1 GITHUB_ENV（动态设置env变量）

8.5.2 读取 GitHub 内置环境变量

8.5.3 secrets（私密变量）

8.5.4 env变量 vssecrets

9 uses语法

官方文档

5.1 `runs-on`语法结构

5.3.1 标签实现多个`runs-on`

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

5.4 `runs-on`的完整示例

6.1 `steps`语法结构

6.2 `steps`关键字段解析

6.2.1 `name`（步骤名称）

6.2.2 `id`（步骤 ID）

6.2.3 `uses`（使用 GitHub 组件）

6.2.4 `run`（运行 Shell 命令）

6.2.5 `with`（传递参数）

6.2.6 `env`（环境变量）

6.2.7 `if`（条件执行）

6.3 `steps`组合示例

7.1 `strategy`语法结构

7.2 `matrix`（矩阵构建）

7.3 组合多个`matrix`变量

7.4 `exclude`（排除某些组合）

7.5 `include`（添加额外组合）

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

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

7.8 `strategy`组合示例

8.1 `env`变量的三种作用域

8.2 `env`语法结构

8.3 `env`变量的作用范围

8.4 使用`env`变量

8.5 `env`变量的高级用法

8.5.1 `GITHUB_ENV`（动态设置`env`变量）

8.5.3 `secrets`（私密变量）

8.5.4 `env`变量 vs`secrets`

9 `uses`语法