企业官网建设流程全解析

GitHub Actions CI/CD 速查手册：Workflow 语法、事件触发与自动化实战（Reference 项目指南）

【免费下载链接】reference⭕ Share quick reference cheat sheet for developers.项目地址: https://gitcode.com/gh_mirrors/re/reference

本指南以 Reference 开源仓库中的 GitHub Actions 速查表（source/_posts/github-actions.md）为骨架，系统讲解 GitHub Actions 的 Workflow 文件编写、触发事件、Job/Step 编排、Runner 选择、Secrets 管理、Artifacts 与缓存、矩阵策略、条件表达式及并发控制等核心知识点。读完本文，你将能够从零编写一套可在 GitHub 仓库中直接运行的 CI/CD 流水线，并理解如何将本仓库这样的 Hexo 静态站点项目（构建脚本见 package.json）接入 GitHub Actions 实现自动化构建、测试与部署。

一、GitHub Actions 是什么

GitHub Actions 是 GitHub 官方提供的 CI/CD（持续集成 / 持续交付）平台，它允许开发者在 GitHub 仓库中直接自动化软件工作流——包括构建（build）、测试（test）和部署（deploy）代码。与传统的独立 CI 服务器不同，GitHub Actions 深度集成于仓库生态：事件（如 push、pull_request）天然与仓库操作绑定，Secrets 存储、Artifacts 下载、运行日志查看等能力也直接内置于仓库的 Web 界面中。

在 Reference 项目中，GitHub Actions 速查表被归类于 Toolkit 分类，面向的典型场景包括：

• 每次提交代码后自动运行单元测试与 lint 检查；
• 在多种 Node.js 版本、多种操作系统上执行矩阵构建；
• 构建产物（如静态站点 HTML）通过 Artifacts 交付或自动部署。

二、快速开始：Workflow 文件与第一个工作流

GitHub Actions 的工作流（Workflow）定义在特殊的 YAML 文件中，通常存放在仓库的.github/workflows目录下（每个仓库可包含多个工作流文件，每个文件即一个独立工作流）。

以下是最小可运行的示例（hello-world）：

name: hello-world on: push jobs: hello-world-job: runs-on: ubuntu-latest steps: - name: Hello World run: echo "Hello World!"

查看工作流运行结果：

• 在 GitHub.com 上进入仓库主页；
• 在仓库名称下方点击Actions标签；
• 在左侧边栏点击要查看的工作流，本例即hello-world。

此时可以看到每次触发的运行记录、每个 Job 的日志、Artifacts 与部署信息。注意on: push是简写形式，等价于on: [push]，表示仓库发生任何 push 事件时触发该工作流。

三、Workflow 语法逐行解析

一个更完整的示例learn-github-actions展示了 Workflow 的核心关键字：

name: learn-github-actions run-name: ${{ github.actor }} is learning GitHub Actions on: [push] jobs: check-bats-version: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v3 with: node-version: '14' - run: npm install -g bats - run: bats -v

逐行语法说明：

值得留意的是，uses:使用owner/repo@ref的格式固定引用 Action 版本（如actions/checkout@v4），这是 GitHub 官方推荐的稳妥做法——将 Action 锁定在具体的 tag 或 commit SHA 上，避免上游变更意外破坏流水线。

四、触发事件（Events）：何时运行工作流

on:关键字定义工作流的触发事件。以下示例在每次 push 时触发：

name: Event-trigger-on-push-example on: [push] # event is defined here jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - name: Run a script run: echo "This workflow runs on every push to the repository."

常见事件触发一览表：

多个事件可以写成数组，例如on: [push, pull_request]；而schedule、workflow_dispatch等事件还支持with/inputs等更细粒度的配置，可按需查阅对应官方说明。

五、Job 与 Step：编排你的流水线

单 Job 示例

name: Single Job on: [push] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - name: Run a build script run: script/build

多 Job 示例

一个工作流中可以定义多个 Job，它们默认并行执行、相互独立：

name: CI Workflow on: [push] jobs: job-1: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - name: Runs job 1 run: echo "Running Job 1" job-2: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - name: Runs job 2 run: echo "Running Job 2" job-3: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - name: Runs job 3 run: echo "Running Job 3"

Step：Job 内的最小执行单元

Step 是 Job 内按声明顺序执行的任务序列，典型模式是「检出代码 → 配置环境 → 安装依赖 → 运行测试」：

jobs: build: runs-on: ubuntu-latest steps: # step 1 - name: Check out repository uses: actions/checkout@v2 # step 2 - name: Set up Node.js uses: actions/setup-node@v2 with: node-version: '14' # step 3 - name: Install dependencies run: npm install # step 4 - name: Run tests run: npm test

实战延伸：将 Reference 仓库接入 CI

以本仓库（Reference，一个基于 Hexo 的静态文档站点）为例，其构建与质量检查脚本定义在 package.json 中：

• test脚本（第 20 行）执行run-s lint:check format:check，即 ESLint 检查与 Prettier 格式校验；
• build脚本（第 9-14 行）依次执行hexo clean、postcss样式编译、hexo generate静态页生成以及gulp资源压缩；
• 依赖管理使用 pnpm（仓库根目录存在 pnpm-lock.yaml）。

因此，一个面向该仓库的 CI 工作流可以写成如下形式：

name: Reference CI on: [push, pull_request] jobs: check-and-build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: pnpm/action-setup@v2 - uses: actions/setup-node@v4 with: node-version: '20' cache: pnpm - run: pnpm install --frozen-lockfile - run: pnpm test - run: pnpm build

其中--frozen-lockfile保证严格按锁文件安装依赖，这正是 CI 中可复现构建的关键。该示例展示了「原文档中的通用语法 + 仓库真实脚本」如何组合出可运行的流水线。

六、Runner：GitHub 托管与自托管

Runner 是执行 Job 的运行环境，通过runs-on指定。

GitHub 托管 Runner

GitHub 提供开箱即用的托管 Runner，ubuntu-latest是最常用的默认选择：

name: Workflow on: [push] jobs: build: runs-on: ubuntu-latest # default runner steps: - uses: actions/checkout@v2 - name: Run a script run: echo "Hello, world!"

自托管 Runner（Self-Hosted Runner）

当需要定制硬件、内网环境或专用操作系统时，可以注册自托管 Runner，并将runs-on指定为self-hosted：

name: Workflow with Self-Hosted Runner on: [push] jobs: build: runs-on: self-hosted steps: - uses: actions/checkout@v2 - name: Run a script run: echo "Hello from self-hosted runner!"

从速查表的编排方式可以看出：runs-on仅影响 Job 运行所在的机器，Job 内的 Step 编写方式完全一致，因此可以在托管与自托管 Runner 之间平滑迁移。若使用自托管 Runner，建议在.github/workflows的 Runner 标签上做好区分（例如runs-on: [self-hosted, linux]），以便同一仓库中混用不同类型的 Runner。

七、环境变量与 Secrets

环境变量（Environment Variables）

在 Job 或 Step 级别通过env:定义自定义变量：

jobs: build: runs-on: ubuntu-latest env: CUSTOM_VARIABLE: 'Hello, World!' # Custom variable defined using env: steps: - name: Check environment variable run: echo "Value of CUSTOM_VAR is $CUSTOM_VAR"

注意：上例定义的是CUSTOM_VARIABLE，而 echo 引用的是$CUSTOM_VAR，二者并不一致——实际运行时环境变量名为CUSTOM_VARIABLE，引用时应保持变量名完全一致。

Secrets（仓库机密）

Secrets 用于存放 Token、密码等敏感信息，它们不会出现在日志中。添加仓库级 Secret 的路径为：

Repository（仓库）>Settings（设置）>Security（安全）>Secrets and Variables>Actions>New Repository Secret

使用 Secrets 的示例工作流：

name: Workflow with Secrets on: [push] jobs: example_job: runs-on: ubuntu-latest steps: - name: Checkout repository uses: actions/checkout@v2 - name: Use a secret run: echo "The secret is ${{ secrets.MY_SECRET }}"

在 Step 中通过${{ secrets.MY_SECRET }}表达式引用。需要注意的是，GitHub 会在运行日志中对 Secret 值打码脱敏，因此上述示例中 Secret 不会以明文出现在日志里；实践中应避免将 Secret 直接 echo 输出，而应将其写入环境变量或配置文件供后续命令读取。Secrets 的可见范围从大到小依次为 组织级（Organization）、仓库级（Repository）与 环境级（Environment），可按需选择。

八、Artifacts 与依赖缓存

Artifacts：交付与保存构建产物

Artifacts 用于在工作流运行间保存构建产物（如编译后的二进制、打包的静态文件）。访问方式：

Repository（仓库）>Actions>Workflow Run（具体运行记录）>Artifacts

jobs: build: runs-on: ubuntu-latest steps: - name: Build project run: make build - name: Upload build artifact uses: actions/upload-artifact@v3 # upload Artifacts prebuilt action with: name: my-artifact path: path/to/artifact

actions/upload-artifact通过name指定产物名称、path指定要上传的文件或目录。下游 Job 可用actions/download-artifact下载，从而实现在不同 Job 之间传递构建结果（例如「构建 Job 上传 → 部署 Job 下载」的流水线拆分）。

缓存依赖：加速工作流

依赖缓存（Dependency Cache）用于存储下载好的依赖包或已编译的二进制文件，从而跳过重复下载、显著加速后续运行：

jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - name: Cache dependencies uses: actions/cache@v2 # stores downloaded packages or compiled binaries with: path: | path/to/dependencies another/path key: ${{ runner.os }}-deps-${{ hashFiles('**/lockfile') }} # hash of the dependency lock file is generated in the OS - name: Install dependencies run: install-command

关键点在于key的构造：${{ runner.os }}表示当前 Runner 的操作系统，hashFiles('**/lockfile')对依赖锁文件（如package-lock.json、pnpm-lock.yaml）内容取哈希。当锁文件未变化时缓存命中，依赖直接复用；锁文件一旦变化，哈希随之改变，便会重新生成缓存——这正是缓存一致性的核心保障。

九、Matrix 矩阵策略：一次声明、多环境并行验证

Matrix 策略允许在多个「版本 × 操作系统」组合上并行运行同一 Job，特别适合验证库的跨版本兼容性：

jobs: build: runs-on: ubuntu-latest strategy: matrix: node-version: [12.x, 14.x, 16.x] # matrix strategy runs enables you to run jobs across multiple combinations of environments and OS's os: [ubuntu-latest, windows-latest, macOS-latest] steps: - uses: actions/checkout@v2 - name: Use Node.js ${{ matrix.node-version }} uses: actions/setup-node@v1 with: node-version: ${{ matrix.node-version }} - run: npm install - run: npm test env: CI: true

说明：

• strategy.matrix下声明的node-version与os数组会做笛卡尔积组合（本例共 3×3=9 种组合），每个组合生成一个并行运行的 Job；
• 在 Step 中通过${{ matrix.node-version }}、${{ matrix.os }}等表达式动态引用当前组合的取值；
• 注意：runs-on中应引用${{ matrix.os }}才能真正跨 OS 运行，本例将runs-on固定为ubuntu-latest，读者可自行将之改为runs-on: ${{ matrix.os }}以获得完整的矩阵能力；
• 如需排除某些组合（如 Windows 上不跑某个版本），可使用matrix.exclude追加排除规则；
• 在run: npm test的 Step 上通过env: CI: true注入环境变量，是很多测试框架（如 Jest）在 CI 环境下切换行为的通用约定。

十、条件表达式（Conditions）：按需执行 Step

if:条件表达式控制 Step 是否执行，常用的判断来源是github上下文。

分支条件

jobs: build: runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkout@v2 - name: Run build if: github.ref == 'refs/heads/main' # "Run build" step will only execute if the current branch is main. run: make build

上例中github.ref == 'refs/heads/main'表示仅当当前分支为main时才执行Run build，可用于实现「仅在主干分支发布/构建」的语义。

事件触发条件

jobs: test: runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkout@v2 - name: Run tests if: github.event_name == 'pull_request' # "Run tests" step is executed only when the workflow is triggered by a pull request event run: npm test

github.event_name == 'pull_request'表示仅当工作流由 pull request 事件触发时才执行测试。条件表达式支持&&、||、!等逻辑运算，也可结合secrets、env、matrix、runner等上下文进行组合判断，例如if: matrix.os == 'ubuntu-latest' && github.event_name == 'push'。

十一、Workflow 命令与并发控制

Workflow Commands：在 Step 间传递状态

Workflow 命令是运行器（Runner）提供的特殊语法，通过echo "..." >> 文件的方式把状态写入 GitHub 环境文件。最常用的场景是在 Step 间传递环境变量：

steps: - name: Set environment variable run: echo "NAME=value" >> $GITHUB_ENV

当运行在ubuntu-latest等 Linux 环境时，bash 命令可以直接使用。写入$GITHUB_ENV的环境变量对后续所有 Step 生效；同理还有$GITHUB_OUTPUT（Step 输出，供后续 Step 通过steps.<id>.outputs读取）、$GITHUB_PATH（追加 PATH）等环境文件，共同构成 Step 间数据传递的官方通道。

Concurrency：避免重复运行冲突

concurrency字段基于分组控制并发。其经典语义是：如果同一分组内有新的运行启动，则取消该分组中仍在进行中的旧运行。原速查表中的示例基于github.head_ref（PR 头分支引用）分组：

jobs: my_job: runs-on: ubuntu-latest concurrency: group: ${{ github.head_ref }} cancel-in-progress: true steps: - name: Run a script run: echo "Running script..."

这样，当开发者对同一分支连续 push 时，旧版本的工作流会被自动取消，只保留最新一次运行，既节省了 Runner 资源，也避免了「旧构建与最新代码不一致」的误导。concurrency也可以声明在 Job 外层的工作流级别，从而控制整个工作流的并发。

十二、相关速查表延伸阅读

GitHub Actions 的 Workflow 文件本身使用 YAML 语法编写，事件、上下文表达式的展开又依赖 GitHub 平台能力，可以参考 Reference 仓库中的以下相邻速查表继续深入：

• YAML 速查表：掌握on:、jobs:、with:等关键字的 YAML 语法基础（缩进、列表、映射、多行字符串），是编写正确 Workflow 文件的前提；
• GitHub 快捷键速查表：涵盖 GitHub.com 站点的常用键盘快捷键，可提升在 Actions 页面、代码与 PR 之间切换的浏览效率；
• 本速查表源文件：source/_posts/github-actions.md。

将以上知识点串联起来，即可完成从「事件触发 → Job/Step 编排 → 环境与密钥管理 → 构建产物交付 → 缓存与矩阵加速 → 条件与并发控制」的完整 GitHub Actions 自动化闭环。无论是本仓库这类 Hexo 静态站点，还是常规的 Node.js/前端项目，都可以基于本文的语法骨架快速搭建自己的 CI/CD 流水线。

【免费下载链接】reference⭕ Share quick reference cheat sheet for developers.项目地址: https://gitcode.com/gh_mirrors/re/reference