Skip to content
CI/CD 基础用法：用 GitHub Actions 配置第一个流水线
概述
理清流水线、阶段、任务这些抽象单元之后，这一章的目标是编写一个可以实际运行的 GitHub Actions 工作流。工作流做的事情不复杂：代码推送到 GitHub 时，自动执行代码检查、测试，然后生成一个可直接下载的构建产物。
GitHub Actions 的配置载体是仓库中的 YAML 文件，也就是工作流文件。把它当成流水线的“代码化描述”理解即可，编辑它和编辑普通源码没有区别。这也意味着工作流文件的变更可以通过 Pull Request 评审，版本回溯同样直接——这是 Pipeline as Code 带来的一个实际好处。
工作流文件的最小结构
一个能被 GitHub Actions 识别的工作流文件至少需要三项：
name：工作流名称，可省略，但保留能让 Actions 面板更可读。on：触发事件，定义什么动作会启动这个工作流。jobs：至少包含一个作业，作业里可以只有一个步骤。
最精简的实例如下：
yaml
name: minimal
on: [push]
jobs:
hello:
runs-on: ubuntu-latest
steps:
- run: echo "workflow triggered"把这个文件保存为 .github/workflows/minimal.yml 并推送到仓库，GitHub 检测到 push 事件后就会启动 hello 作业，在 ubuntu 运行器中执行一条 echo 命令。如果仓库原本没有 .github/workflows 目录，在 GitHub 网页上创建文件时直接输入完整路径（如 .github/workflows/minimal.yml）即可一次性建好目录和文件。
工作流文件的扩展名必须是 .yml 或 .yaml，文件名没有强制规定，但描述性名称更利于维护。
设定触发事件
on 字段控制监听哪些仓库事件。几种最常用的写法：
on: [push]— 任何分支有推送时触发。on: [push, pull_request]— 推送或创建/更新 Pull Request 时触发。on: workflow_dispatch— 允许在 Actions 面板中手动触发，适合需要人工确认的重跑场景。
这里方括号是 YAML 的数组写法，即使只有一个事件也不能省略，否则会解析错误。
如果只在特定分支上触发 push，可以用对象写法：
yaml
on:
push:
branches:
- main
- 'releases/**'
pull_request:
branches:
- mainworkflow_dispatch 不依赖 Git 事件，配置后会在仓库的 Actions 选项卡里多出一个“Run workflow”按钮。临时验证一个工作流时常会用到，不必为了触发而特意提交一次代码。
作业与步骤：从检出到执行脚本
指定运行环境
jobs 下每个作业通过 runs-on 指定运行环境，即 GitHub 托管运行器的操作系统和版本：
yaml
jobs:
build:
runs-on: ubuntu-latest常用标签：
ubuntu-latest（目前对应 Ubuntu 22.04）windows-latestmacos-latest
GitHub 为不同标签提供不同预装软件的运行器实例。对于 Node.js 项目，ubuntu-latest 是最常用的选择。
检出代码
steps 里的第一个动作几乎总是 actions/checkout——把仓库代码克隆到运行器的当前工作目录。后面所有对自己代码的操作都依赖这一步：
yaml
steps:
- name: Check out repository code
uses: actions/checkout@v4uses 表示引用一个社区或官方的 Action，actions/checkout 是 GitHub 维护的官方 Action。指定版本号（如 @v4）可以固定行为，避免上游更新导致意外变化。默认情况下，checkout 只拉取触发工作流的那个 ref 的最新一次提交；如果需要完整提交历史（例如生成 changelog），可以设置 fetch-depth: 0。
执行命令
run 让步骤直接在运行器的 Shell 中执行命令。单行写法：
yaml
- name: Install dependencies
run: npm ci多行时用 | 保持可读性：
yaml
- name: Print debug info
run: |
echo "Event: ${{ github.event_name }}"
echo "Branch: ${{ github.ref }}"${{ }} 是表达式语法，用来访问 GitHub Actions 的上下文对象。常用上下文：
github.event_name— 触发事件名称，如push、pull_requestgithub.ref— 分支或标签引用github.repository— 仓库全名runner.os— 运行器操作系统
这些值由平台注入，不需要手动设置，常用于产生活动日志或条件判断。需要注意，上下文表达式不能和 Shell 变量直接拼接，必须作为独立字符串传入——上面的写法是正确的。
run 执行的 Shell 在 ubuntu 上是 bash，Windows 上是 PowerShell。跨平台命令需要考虑兼容性，或者显式指定 shell: bash。
串联代码检查、测试与构建
有了上面的基础，串联多个步骤就是按顺序写出一组 run 或 uses。以一个 TypeScript/Node.js 项目为例，目标是：安装依赖 → 静态检查（lint）→ 运行测试 → 构建产物。
yaml
name: Node.js CI
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
- name: Install dependencies
run: npm ci
- name: Lint
run: npm run lint
- name: Test
run: npm test
- name: Build
run: npm run build这里用到了 actions/setup-node@v4 来指定 Node.js 版本，它会在运行器上安装并配置好 Node.js 和 npm 环境。npm ci 比 npm install 更严格：严格按照 package-lock.json 安装，且会先清除 node_modules，适合在持续集成环境中保证依赖的一致性。
步骤之间的依赖关系是线性的：前一步失败，后续步骤就不会执行。这意味着如果 lint 报错，测试和构建就不会跑，能避免浪费运行时间。
上传并下载构建产物
作业执行完后，运行器实例会被回收，上面生成的文件也随之消失。构建出的 dist/ 或者压缩包如果希望后续使用，需要用 actions/upload-artifact 上传到 GitHub 的制品存储中。
在同一个工作流的后续作业中，可以通过 actions/download-artifact 取回这些产物。下面是一个完整示例：先构建并上传，再由另一个作业下载验证。
yaml
name: Build and Package
on:
push:
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '20'
- run: npm ci
- run: npm run build
- uses: actions/upload-artifact@v4
with:
name: dist-output
path: dist/
download-and-verify:
needs: build
runs-on: ubuntu-latest
steps:
- uses: actions/download-artifact@v4
with:
name: dist-output
- run: ls -laupload-artifact 把 dist/ 目录上传为一个名为 dist-output 的制品，download-artifact 在第二个作业中根据名称取出并存放在当前工作目录。needs: build 表示 download-and-verify 等待 build 完成后才启动，由此实现了作业之间的顺序和产物传递。path 参数支持通配符和目录，但它相对的是 $GITHUB_WORKSPACE 目录。
关于制品的限制：
- 每个工作流运行最多上传 500 个制品。
- 单个制品大小有上限（GitHub Free 计划下较小），超出会报错。
- 制品在仓库的 Actions 运行详情页中可见且可下载，默认保留 90 天。
在 Actions 面板中解读执行结果
工作流被触发后，在仓库顶部的“Actions”选项卡中可以查看所有运行记录。每条记录包含：
- 运行状态（黄色 in progress、绿色 success、红色 failure、灰色 cancelled）
- 每个作业的独立日志
- 每个步骤的展开详情，带有命令输出和持续时间
- 如果上传了制品，页面底部会有一个“Artifacts”区域，可以直接点击下载
点击某个失败作业的步骤，日志会精确显示哪条命令报错以及错误输出。上下文变量在日志中也会原样展开，方便定位是哪个分支、哪个事件触发了问题。
如果仓库没有显示“Actions”选项卡，多半是该仓库的 Actions 功能被禁用了，需要在仓库的 Settings → Actions → General 中把 Actions permissions 调整为“Allow all actions”或者允许指定的 actions。
注意点
- 工作流文件必须在
.github/workflows目录下，扩展名为.yml或.yaml。在 GitHub 网页上创建文件时，输入完整路径可自动创建缺失的目录。 - 触发事件
on: [push]中的方括号是 YAML 数组语法，即使只有一个事件也不能省略。 actions/checkout默认只拉取触发工作流的那个 ref 的最新提交。如果需要完整历史（例如用于生成 changelog 或计算增量变更），设置fetch-depth: 0。run执行的 Shell 在 ubuntu 上是 bash，Windows 上是 PowerShell。跨平台命令需要考虑兼容性，或者显式设置shell: bash。- 上下文表达式
${{ }}不能与 Shell 变量直接拼接，必须作为独立字符串传入。 - 使用
actions/upload-artifact时，path参数相对的是$GITHUB_WORKSPACE目录，支持通配符和目录路径。 - GitHub 提供了大量工作流模板。仓库第一次打开 Actions 页时会根据项目语言推荐模板（如 Node.js、Python、Java），可以直接套用再微调。