第3章 GitHub Actions YAML语法基础：name、on、jobs、steps、uses、run、env、with
3.1 YAML 语法与 GitHub Actions 结构概述
GitHub Actions 工作流使用 YAML 格式定义，其核心语法围绕几个顶层字段展开。正确理解 name、on、jobs、steps、uses、run、env 和 with 的作用与相互关系，是编写可靠 CI/CD 工作流的基础。
YAML 缩进规则：GitHub Actions 严格按空格缩进（2 个空格），不允许使用 Tab。缩进错误会导致工作流解析失败。
3.2 字段定义与用途对照表
| 字段 | 作用域 | 说明 | 示例 |
|---|---|---|---|
name | 顶层 | 工作流名称，显示在 Actions 页面 | name: CI Pipeline |
on | 顶层 | 触发事件（push、pull_request、schedule 等） | on: push |
jobs | 顶层 | 定义一个或多个作业（job） | jobs: { … } |
steps | job 内 | 作业内执行的步骤序列 | steps: [ … ] |
uses | step 内 | 引用其他 Action（GitHub 官方、社区或本地） | uses: actions/checkout@v4 |
run | step 内 | 执行 shell 命令或脚本 | run: echo "Hello" |
env | job/step/顶层 | 设置环境变量 | env: { KEY: value } |
with | step 内（配合 uses） | 向复用的 Action 传递输入参数 | with: { node-version: '18' } |
3.3 完整工作流示例
以下示例展示了一个典型的 CI 工作流，触发条件为 push 到 main 分支，包含一个 build 作业。
name: CI Workflow
on:
push:
branches:
- main
jobs:
build:
runs-on: ubuntu-latest
env:
NODE_VERSION: '18'
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Set up Node.js
uses: actions/setup-node@v4
with:
node-version: ${{ env.NODE_VERSION }}
- name: Install dependencies
run: npm ci
- name: Run tests
run: npm test
env:
CI: true
要点说明：
env 可以在 job 级别定义（继承给所有 steps），也可以在 step 级别单独覆盖；with 必须配合 uses 使用，传入的参数内容由 Action 作者定义。
3.4 字段层级关系流程图
下图展示了 main、on、jobs、steps 之间的树形包含关系，以及 uses、run、env、with 在 step 中的位置。
3.5 调试方法与常见错误
3.5.1 使用 act 本地调试
act 工具允许在本地运行 GitHub Actions 工作流，快速验证语法与逻辑。
# 安装 act (macOS)
brew install act
# 运行工作流
act push --job build3.5.2 常见错误列表
- 缩进不一致：混合使用空格和 Tab，或缩进层级不对。例如
steps应该缩进在job内。 - 字段拼写错误：如将
uses写成use，将runs-on写成runson。 - env 的作用域误解：在 step 中定义的
env仅在该 step 内生效；job 级别的env则不自动传入with参数（需要通过${{ env.VAR }}显式引用）。 - with 未与 uses 配对：
with只能出现在使用uses的 step 中，不能单独用于run步骤。 - on 事件类型错误：例如
push写成pushe，或忘记加分支过滤。
陷阱提醒：在
run 步骤中直接使用未转义的 ${{ }} 表达式可能导致语法错误。建议将复杂逻辑放在 env 或脚本中。
3.6 性能与稳定性优化
3.6.1 减少重复 step 的冗余 uses
一个 job 内编排多个相同 Action 时，考虑合并到单个 step 或使用矩阵策略，避免多次加载相同 Action。
3.6.2 合理使用 env 与环境变量
将硬编码的密钥、版本号提取到 env 或 GitHub Secrets 中，提高可维护性。
3.6.3 利用 with 参数控制 Action 行为
大部分社区 Action 提供 with 参数来定制行为。阅读文档并仅传递必要参数，避免传递未使用的值造成意外开销。
3.7 小结
name、on、jobs、steps、uses、run、env、with 构成了 GitHub Actions YAML 的核心语法。掌握它们的作用范围与组合规则，可以编写出结构清晰、易于调试和扩展的 CI/CD 工作流。