GitHub Actions YAML 文件中 runs-on 和 uses 这两个最核心和关键指令的作用与区别。

总结（TL;DR）

• runs-on: 指定在哪种机器上运行 job 或 step。它定义的是运行环境（例如 Ubuntu, Windows, macOS）。
• uses: 指定运行什么。它用于复用已有的 Action（代码），这个 Action 可以来自官方仓库、公共市场或你的私有仓库。它定义的是执行内容。

---

1. runs-on - 指定运行环境

作用：runs-on 指令用于指定一个 Job 或 Step 将在哪种类型的运行器（Runner） 上执行。运行器是托管工作流程的虚拟机或物理机。

级别：它主要定义在 Job 级别（最常见），但从某些版本的 GitHub Actions 开始，也可以在个别 Step 中覆盖（尽管不常用）。

常用值：

• 操作系统：指定虚拟环境的操作系统。
  • ubuntu-latest 或 ubuntu-22.04（最常用，免费且速度快）
  • windows-latest
  • macos-latest
• 运行器标签：如果你使用自托管的（self-hosted）运行器，你可以使用你为其配置的标签，例如 runs-on: [self-hosted, linux, x64, gpu]。

示例： 在这个例子中，整个 build-job 将在 GitHub 提供的最新版 Ubuntu 虚拟机上运行。

yaml
jobs:
  build-job:
    runs-on: ubuntu-latest # 这个job在Ubuntu系统上运行
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Run a script
        run: echo "Hello World from Ubuntu!"

---

2. uses - 复用 Action

作用：uses 指令用于从一个 Step 中复用一个 Action。Action 是 GitHub Actions 平台的可重用单元，你可以把它想象成一个函数或一个封装好的脚本。它允许你直接使用别人或自己写好的功能，而无需重复编写复杂的脚本。

级别：它只在 Step 级别使用。

常用值：

• 官方市场 Action：格式为 {owner}/{repo}@{ref}
  • actions/checkout@v4：最常用的 Action，用于将你的仓库代码签出（下载）到运行器的工作目录。
  • actions/setup-node@v3：用于安装指定版本的 Node.js。
  • actions/setup-python@v4：用于安装指定版本的 Python。
• 同一仓库中的本地 Action：格式为 ./path/to/action-directory
• Docker Hub 上的公共容器镜像：格式为 docker://{image}:{tag}

示例： 在这个例子中，第一个 Step 使用（uses） 了 actions/checkout 这个官方 Action 来获取代码。第二个 Step 使用（uses） 了 actions/setup-node 这个 Action 来安装 Node.js 环境。

yaml
jobs:
  build-job:
    runs-on: ubuntu-latest
    steps:
      # 使用公共Action：从仓库获取代码
      - uses: actions/checkout@v4

      # 使用公共Action：安装Node.js
      - uses: actions/setup-node@v3
        with: # ‘with’用来传递参数给Action
          node-version: '18'

      # 这个step没有用‘uses’，而是用‘run’来执行shell命令
      - name: Install dependencies and build
        run: |
          npm ci
          npm run build

---

对比表格

特性	runs-on	uses
作用	指定运行环境（在哪里运行）	指定执行内容（运行什么，复用代码）
级别	Job 级别（主要）	Step 级别
值类型	操作系统标签（如 ubuntu-latest) 或自托管运行器标签	Action 的引用（如 actions/checkout@v4) 或 Docker 镜像
类比	选择一台电脑（Windows PC 或 MacBook）	打开电脑上的一个特定软件或运行一个脚本

协同工作

在一个典型的工作流程中，runs-on 和 uses 是协同工作的：

1. runs-on 先为整个 Job 搭建好一个“舞台”（一台干净的虚拟机，比如 Ubuntu）。
2. 然后，每个 Step 中的 uses 在这个“舞台”上执行具体的“动作”或“节目”（比如下载代码、安装环境、执行测试）。
3. 如果一个 Step 没有 uses，它通常会使用 run 来直接执行 shell 命令，这相当于在“舞台”上即兴表演。

希望这个解释能帮助你清晰地理解这两个核心概念！