GitHub Actions 快速入门+场景实践案例

GitHub Actions 快速入门 · 学习笔记

来源:GitHub 官方文档 Actions 快速入门、了解 GitHub Actions、工作流 目标读者:完全没用过 CI/CD、没写过 YAML 的人 。读完之后你能亲手跑起第一个 Actions 工作流,并且看懂别人的 .yml 文件。


目录

  1. [先搞懂:GitHub Actions 到底在干什么](#先搞懂:GitHub Actions 到底在干什么 "#1-%E5%85%88%E6%90%9E%E6%87%82github-actions-%E5%88%B0%E5%BA%95%E5%9C%A8%E5%B9%B2%E4%BB%80%E4%B9%88")
  2. [一套心智模型:5 个名词就够了](#一套心智模型:5 个名词就够了 "#2-%E4%B8%80%E5%A5%97%E5%BF%83%E6%99%BA%E6%A8%A1%E5%9E%8B5-%E4%B8%AA%E5%90%8D%E8%AF%8D%E5%B0%B1%E5%A4%9F%E4%BA%86")
  3. [动手前的准备(3 个条件)](#动手前的准备(3 个条件) "#3-%E5%8A%A8%E6%89%8B%E5%89%8D%E7%9A%84%E5%87%86%E5%A4%873-%E4%B8%AA%E6%9D%A1%E4%BB%B6")
  4. 第一步:创建你的第一个工作流文件
  5. [第二步:读懂这份 YAML(逐行讲解)](#第二步:读懂这份 YAML(逐行讲解) "#5-%E7%AC%AC%E4%BA%8C%E6%AD%A5%E8%AF%BB%E6%87%82%E8%BF%99%E4%BB%BD-yaml%E9%80%90%E8%A1%8C%E8%AE%B2%E8%A7%A3")
  6. 第三步:提交并触发运行
  7. 第四步:查看运行结果和日志
  8. 常见坑与排错清单
  9. [真实开发场景:10 份可直接改的配置](#真实开发场景:10 份可直接改的配置 "#9-%E7%9C%9F%E5%AE%9E%E5%BC%80%E5%8F%91%E5%9C%BA%E6%99%AF10-%E4%BB%BD%E5%8F%AF%E7%9B%B4%E6%8E%A5%E6%94%B9%E7%9A%84%E9%85%8D%E7%BD%AE")
  10. 进阶路线:接下来学什么
  11. 附录:速查表与术语表

1. 先搞懂:GitHub Actions 到底在干什么

一句话:

GitHub Actions 是一个"事件驱动的自动化执行平台",代码一有变化,它就帮你自动跑一串命令。

它最常见的用途叫 CI/CD:

  • CI(持续集成):每次有人提交代码,自动装依赖、跑测试,防止"改坏了没人发现"。
  • CD(持续交付/部署):测试通过后自动打包、发布、部署到服务器。

但它的能力不止于此。只要仓库里发生了"事件",就能触发:

你想要的自动化 对应的事件
每次 push 跑测试 + 检查格式 push
有人提 PR 时自动跑测试、卡住合并 pull_request
有人新建 Issue 时自动打标签、分配给负责人 issues
每天凌晨自动跑一次数据抓取 schedule(cron)
手动点一下按钮就发布 workflow_dispatch

关键认知:不需要你买服务器、装环境、写守护进程。 你在仓库里放一个 .yml 文本文件,GitHub 就会在自己的机器上帮你跑------跑完就销毁。


2. 一套心智模型:5 个名词就够了

这是全篇最重要的一节。把这 5 个词的关系记住,后面所有内容都是它的展开。

less 复制代码
事件 (event)  ──触发──▶  工作流 (workflow)
                              │
                              ├─▶ 作业 A (job)  ──▶ 运行器 (runner: ubuntu-latest)
                              │        ├─ 步骤 1:执行命令 run: ...
                              │        ├─ 步骤 2:用别人写好的动作 uses: ...
                              │        └─ 步骤 3:...
                              │
                              └─▶ 作业 B (job)  ──▶ 另一个运行器(和 A 并行)
名词 英文 通俗解释 在文件里怎么写
事件 event 触发条件,"什么情况下开始干活" on:
工作流 workflow 一个完整的自动化流程,就是一个 .yml 文件 name:
作业 job 工作流里的一件"大事",每个作业独占一台机器 jobs: 下的键
步骤 step 作业里的一小步,要么跑 shell 命令,要么调用现成的动作 steps: 列表
运行器 runner 真正跑作业的机器(GitHub 免费提供 Ubuntu / Windows / macOS 虚拟机) runs-on:
动作 action 别人写好的可复用模块(相当于 npm 包 / pip 包) uses:

三个必须记住的规则:

  1. 工作流文件必须放在仓库的 .github/workflows/ 目录下 ,扩展名必须是 .yml 或 .yaml。放错地方 GitHub 根本不会发现它。
  2. 步骤之间是串行的 (同一台机器上,按顺序执行,能共享文件);作业之间默认并行 ,除非你用 needs: 声明依赖。
  3. 每个作业都是在一台全新的干净虚拟机上运行,跑完即销毁。所以上一个作业生成的文件,下一个作业默认看不到(要共享得用 artifact)。

3. 动手前的准备(3 个条件)

  • 会基本用 GitHub:知道什么是仓库(repository)、提交(commit)、分支(branch)、拉取请求(PR)。
  • 有一个自己的仓库,并且你有权限往里加文件(自己的仓库,或别人的仓库给你写权限)。
  • 仓库的 Actions 功能是开启的 :打开仓库,顶部能看到 Actions 标签页。 如果看不到 Actions 标签,通常是被关掉了。去 Settings → Actions → General 打开。

小技巧:不想污染正式项目,就新建一个空仓库专门用来练手,随便怎么折腾。


4. 第一步:创建你的第一个工作流文件

我们要创建的文件路径是:.github/workflows/github-actions-demo.yml

4.1 在网页上创建(推荐新手)

有两种情况,取决于目录是否已存在:

情况 A:仓库里已经有 .github/workflows/ 目录

  1. 进入该目录。
  2. 点 Add file → Create new file。
  3. 文件名填 github-actions-demo.yml。

情况 B:仓库里什么都没有(全新仓库)

  1. 回到仓库主页,点 Add file → Create new file。

  2. 文件名一次性输入完整路径:

    bash 复制代码
    .github/workflows/github-actions-demo.yml

    GitHub 会自动帮你创建 .github 和 workflows 这两个目录------斜杠就是建目录的意思,不用手动一层层建。

关于文件名:

  • 名字随便起(demo.yml、ci.yml、test.yaml 都行),但扩展名必须是 .yml 或 .yaml。
  • YAML 是一种"用缩进表达层级"的配置文件格式,你不需要精通它,注意只用空格缩进、不要用 Tab 就够了。

4.2 把官方示例内容粘进去

把文件内容换成下面这段(这是官方示例,actions/checkout@v6 是当前版本):

yaml 复制代码
name: GitHub Actions Demo
run-name: ${{ github.actor }} is testing out GitHub Actions 🚀
on: [push]
jobs:
  Explore-GitHub-Actions:
    runs-on: ubuntu-latest
    steps:
      - run: echo "🎉 The job was automatically triggered by a ${{ github.event_name }} event."
      - run: echo "🐧 This job is now running on a ${{ runner.os }} server hosted by GitHub!"
      - run: echo "🔎 The name of your branch is ${{ github.ref }} and your repository is ${{ github.repository }}."
      - name: Check out repository code
        uses: actions/checkout@v6
      - run: echo "💡 The ${{ github.repository }} repository has been cloned to the runner."
      - run: echo "🖥️ The workflow is now ready to test your code on the runner."
      - name: List files in the repository
        run: |
          ls ${{ github.workspace }}
      - run: echo "🍏 This job's status is ${{ job.status }}."

⚠️ 注意 :这段 YAML 里全是 ${{ }} 表达式,但 GitHub 网页不会自动转义。如果你是从某个网页复制过来,粘进去之后检查一下缩进有没有被破坏(每级缩进 2 个空格),这是新手最常踩的坑。

4.3 使用现成模板(另一种省事方式)

GitHub 会根据你仓库的代码自动推荐模板(比如检测到 Node.js 就推荐 Node 的 CI)。路径:仓库 → Actions 标签页 → 选一个模板 → Configure → 提交。

模板分类:

  • CI:持续集成(构建、测试)
  • Deployments:部署
  • Automation:自动化日常事务
  • Code scanning:代码扫描(安全)
  • Pages:发布 GitHub Pages

完整模板库:actions/starter-workflows


5. 第二步:读懂这份 YAML(逐行讲解)

别跳过这节------这是从"会复制粘贴"到"会自己写"的分水岭。

5.1 整体骨架

yaml 复制代码
name: 工作流的名字          # ← 第一层
run-name: 每次运行显示的名字
on: 触发条件
jobs:                      # ← 第一层,下面是所有作业
  作业ID:                   # ← 缩进 2 空格
    runs-on: 用哪台机器
    steps:                 # 步骤列表
      - 第一步              # ← 短横线表示"数组里的一项"
      - 第二步

5.2 逐行拆解

name: GitHub Actions Demo

工作流的显示名。在仓库的 Actions 左侧栏里看到的就是它。

run-name: ${{ github.actor }} is testing out GitHub Actions 🚀

某一次运行 的显示名。name 是工作流的名字,run-name 是这次具体运行的名字。 ${{ github.actor }} 是个变量,会被替换成"触发这次运行的人的用户名"。所以你会在运行列表里看到 octocat is testing out GitHub Actions 🚀。

on: [push]

触发条件:有人往仓库 push 代码就运行。

  • [push] 是数组简写,等价于:

    yaml 复制代码
    on:
      - push
  • 更常见的写法是加过滤条件,比如"只在 main 分支被 push 时运行":

    yaml 复制代码
    on:
      push:
        branches: [main]
  • 多个事件:

    yaml 复制代码
    on: [push, pull_request]
jobs:

所有作业的容器。下面每一项(缩进 2 空格)就是一个作业。

Explore-GitHub-Actions:

这是作业的 ID (自己起名,字母数字和 - _)。它在界面上的显示名也是这个。

后面解释:ID 用来被 needs: 引用。

runs-on: ubuntu-latest

指定运行器 (跑这个作业的虚拟机):最新版 Ubuntu。 可选常用值:ubuntu-latest、windows-latest、macos-latest。 (-latest 会随 GitHub 升级;想固定就写具体版本号如 ubuntu-22.04。)

steps:

步骤列表 。下面每行以 - 开头,代表一个步骤。同一作业内的步骤按顺序执行。

5.3 两种步骤:run 和 uses

这是 Actions 里最重要的一个区分:

写法 含义 举例
run: 直接执行 shell 命令 run: npm test
uses: 调用一个现成的 Action uses: actions/checkout@v6

对比看示例:

yaml 复制代码
      - run: echo "🎉 ..."                          # ← 执行命令,没有名字
      - name: Check out repository code             # ← 有名字,方便在日志里识别
        uses: actions/checkout@v6                   # ← 调用动作
  • name: 是可选的人类友好标签,会显示在日志里。强烈建议给每个步骤加 name,出问题时一眼定位。
  • - run: 和 - name: 里的短横线属于同一个步骤 ,所以 name 和 uses/run 要对齐成同样的缩进。

5.4 多行命令和 |

yaml 复制代码
      - name: List files in the repository
        run: |
          ls ${{ github.workspace }}

run: | 表示"下面是多行 shell 脚本,原样执行"。可以写多行:

yaml 复制代码
      - name: 多步操作
        run: |
          echo "第一步"
          npm ci
          npm run build

5.5 ${{ }} 是什么?

这是 上下文表达式(context),Action 运行时会把变量替换成真实值。示例里用到的几个:

表达式 含义 示例输出
${{ github.actor }} 触发者用户名 octocat
${{ github.event_name }} 触发事件名 push
${{ runner.os }} 运行器操作系统 Linux
${{ github.ref }} 完整 Git 引用 refs/heads/main
${{ github.repository }} 仓库全名 octocat/hello-world
${{ github.workspace }} 运行器上的工作目录 /home/runner/work/...
${{ job.status }} 当前作业状态 success

5.6 那个 actions/checkout 到底做了什么?

没有它,运行器上是空的! 运行器是一台全新虚拟机,里面没有你的代码。

actions/checkout@v6 的作用就是:把你的仓库代码 clone 到运行器的工作目录。

所以逻辑链是:

  1. 前 3 步 echo 只打印环境信息,不需要代码,能跑通。
  2. checkout 把代码拉下来。
  3. 后面的 ls 才能列出文件------如果没有 checkout,这里会是一个空目录。
  4. 真实项目里,npm ci / pytest / go build 这些命令,都必须写在 checkout 之后。

记住这个顺序:checkout → setup 环境(node/python...) → 安装依赖 → 构建 → 测试 → 部署

@v6 是版本号,别写 @main(不稳定),也别省略(会报错)。


6. 第三步:提交并触发运行

滚动到页面底部,GitHub 会弹出 Commit changes / Propose changes 对话框,有两个选择:

选项 结果 适合场景
Commit directly to the main branch 直接提交到默认分支 → 立刻触发一次 push 事件 练手、自己的项目
Create a new branch + start a pull request 新建分支并开 PR 团队协作、规范的代码评审

因为示例里写的是 on: [push],只要你把文件提交到任何一个分支,工作流就已经开始跑了------不需要再去点"运行"按钮。

提交完成后,回到仓库首页,稍等几秒,你会看到顶部出现黄色小圆点(运行中)/ 绿色勾(成功)。


7. 第四步:查看运行结果和日志

路径如下(一步步照着点):

  1. 打开仓库主页。
  2. 左侧栏 里找到工作流名字------本例是 GitHub Actions Demo,点它。
  3. 看到运行列表 ,每一行是一次运行。点开想看的那次------名字会是 你的用户名 is testing out GitHub Actions 🚀 (这就是 run-name 的效果)。
  4. 进入运行详情页,左侧 Jobs 下点 Explore-GitHub-Actions。
  5. 右侧显示每一步的日志。点任意步骤可以展开看详细输出。

你会看到什么

  • 每步前面有个绿色勾 = 成功;红色叉 = 失败。
  • 点开 List files in the repository 这一步,能看到 ls 的输出------因为前面 checkout 过,所以这里能列出你的仓库文件。
  • 最后一步会打印 🍏 This job's status is success.

跑失败了怎么看

  1. 先看哪个步骤变红,点开它,读最后的报错信息。
  2. 常见原因:YAML 缩进错、uses 的版本号写错、命令环境里没有这个工具、忘了 checkout。
  3. 修好之后重新提交(再 push 一次)即可重跑,也可以在该次运行页面点 Re-run jobs 重跑。

8. 常见坑与排错清单

现象 原因 解决
Actions 标签页里什么都看不到 文件没放在 .github/workflows/ 下;或扩展名不是 .yml/.yaml 检查路径和扩展名,注意 .github 前面的点
工作流不触发 on: 事件和你的操作不匹配;或 branches: 过滤掉了当前分支 先写 on: [push] 验证,再逐步收紧
报 YAML 语法错误 用了 Tab 缩进、缩进层级不齐、冒号后缺空格 全部用空格,统一 2 空格缩进;key: value 冒号后要有空格
uses 报错找不到 action 少了 @版本,或拼错仓库名 写全 owner/repo@version,如 actions/checkout@v6
命令找不到文件 / 目录是空的 忘了 actions/checkout,或把它放在依赖步骤之后 checkout 必须是第一个实质步骤
第二个作业读不到第一个作业的文件 不同作业跑在不同虚拟机上 用 actions/upload-artifact / download-artifact 传递
中文/emoji 显示乱码 一般不会,Actions 支持 UTF-8 文件保存为 UTF-8
私有仓库跑不动了 免费额度用尽 去 Settings → Billing 查看 Actions 使用量

9. 真实开发场景:10 份可直接改的配置

这一节是"抄作业区"。每份配置都按 场景 → 完整 YAML → 逐块解释"为什么这么配" → 你需要改哪里 组织。 版本号说明:@v4 @v6 这类主版本号是必须写的 (不写会报错,写 @main 则随时可能挂)。具体数字请以各 Action 的 README 为准,本文数字跑得通即可。


场景 1:Vue/React 纯前端项目 → 自动部署 GitHub Pages

最常见的前端场景 :push 到 main 就自动构建并发布,免费、不用服务器。 关键点 :permissions + concurrency + 两段式 build/deploy。

yaml 复制代码
name: Deploy to GitHub Pages

on:
  push:
    branches: [main]
  workflow_dispatch:          # 支持手动点按钮触发

# GitHub Pages 部署必须的三项权限,缺一个就报 403
permissions:
  contents: read
  pages: write
  id-token: write

# 同一时间只跑一个部署,避免两次 push 抢着发布
concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: 拉取代码
        uses: actions/checkout@v6

      - name: 安装 pnpm
        uses: pnpm/action-setup@v4
        with:
          version: 9

      - name: 安装 Node 并启用 pnpm 缓存
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: pnpm            # 自动缓存 pnpm store,二次构建快很多

      - name: 安装依赖
        run: pnpm install --frozen-lockfile   # 严格按 lockfile,锁版本一致

      - name: 构建
        run: pnpm build
        env:
          NODE_ENV: production

      - name: 配置 Pages
        uses: actions/configure-pages@v5

      - name: 上传构建产物
        uses: actions/upload-pages-artifact@v3
        with:
          path: dist             # Vite 默认 dist;CRA 改 build

  deploy:
    needs: build                 # 必须等 build 成功
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: 发布到 Pages
        id: deployment
        uses: actions/deploy-pages@v4

为什么这么配

配置 原因
permissions 三项 Pages 部署走 OIDC,必须 id-token: write。新手 90% 的 Pages 失败都在这
concurrency 两次 push 可能并发部署,互相覆盖。设成串行更安全
cache: pnpm 不加的话每次都要重新下载全部依赖
--frozen-lockfile CI 里绝不要让依赖被悄悄升级,否则"本地能跑线上挂"
build / deploy 拆两个 job 部署环境隔离,且 environment 能记录部署历史、支持回滚

你需要改的 :path: dist 换成你的产物目录;pnpm 版本号;Node 版本。 仓库还需一步 :Settings → Pages → Source 选 GitHub Actions(不是 branch)。

顺手提示:SPA 部署到 Pages 后刷新 404,是因为没有服务端路由回退。解决办法是在 public/ 放一个 404.html,内容为 index.html 的副本(或用 spa-github-pages 技巧)。


场景 2:前端项目 → 部署到 Vercel / Netlify(用 Secrets)

Vercel 自带 Git 集成,但当你要在 CI 里跑测试再部署,或者想控制部署时机,就需要这套。

yaml 复制代码
name: Deploy to Vercel

on:
  push:
    branches: [main]
  pull_request:                 # PR 也部署一份预览环境

env:
  VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
  VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - uses: pnpm/action-setup@v4
        with: { version: 9 }

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: pnpm

      - run: pnpm install --frozen-lockfile

      - name: 质量门禁(先测再发)
        run: |
          pnpm lint
          pnpm test -- --run

      - name: 安装 Vercel CLI
        run: pnpm add -g vercel@latest

      # PR → preview;main → production
      - name: 部署
        run: |
          if [ "${{ github.event_name }}" = "pull_request" ]; then
            vercel deploy --token=${{ secrets.VERCEL_TOKEN }}
          else
            vercel deploy --prod --token=${{ secrets.VERCEL_TOKEN }}
          fi

Secrets 怎么加 :仓库 Settings → Secrets and variables → Actions → New repository secret 需要三个:VERCEL_TOKEN(账号设置里生成)、VERCEL_ORG_ID、VERCEL_PROJECT_ID(本地跑 vercel link 后看 .vercel/project.json)。

新手最容易犯的错:把 token 直接写进 yml。

只要 token 进过 git 历史,即使后来删掉也视为已泄露,必须立刻重新生成。真的泄露了 GitHub 还会给你发邮件告警。

Netlify 版本(同样思路,更短):

yaml 复制代码
      - name: Deploy to Netlify
        run: npx netlify-cli deploy --prod --dir=dist --site=${{ secrets.NETLIFY_SITE_ID }} --auth=${{ secrets.NETLIFY_AUTH_TOKEN }}

场景 3:Node.js 后端 → CI 跑 lint / test / 多版本矩阵(带数据库)

最经典的 CI。这个场景要解决三个问题:跑测试、测多个 Node 版本、测试需要数据库。

yaml 复制代码
name: CI

on:
  push:
    branches: [main, develop]
  pull_request:

# 同一分支的新提交会取消上一次未跑完的 CI,省额度
concurrency:
  group: ci-${{ github.ref }}
  cancel-in-progress: true

jobs:
  test:
    runs-on: ubuntu-latest

    # 矩阵:一次定义,跑 3 份,互不干扰
    strategy:
      fail-fast: false          # 一个版本挂了不要取消其他版本,方便一次看全
      matrix:
        node-version: [18, 20, 22]

    # 服务容器:GitHub 帮你起一个真实的 Postgres
    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_PASSWORD: test
          POSTGRES_DB: app_test
        ports: ['5432:5432']
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5

    env:
      DATABASE_URL: postgres://postgres:test@localhost:5432/app_test

    steps:
      - uses: actions/checkout@v6

      - uses: pnpm/action-setup@v4
        with: { version: 9 }

      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}   # ← 矩阵变量在这里注入
          cache: pnpm

      - run: pnpm install --frozen-lockfile

      - name: 代码检查
        run: pnpm lint

      - name: 类型检查
        run: pnpm typecheck

      - name: 迁移数据库
        run: pnpm db:migrate

      - name: 单元测试 + 覆盖率
        run: pnpm test -- --coverage

      - name: 上传覆盖率报告(失败也能上传)
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: coverage-${{ matrix.node-version }}
          path: coverage/
          retention-days: 7

为什么这么配

配置 原因
services.postgres CI 里不能连公司数据库。用容器起一个临时库,localhost:5432 直接连
--health-cmd pg_isready 不加健康检查的话,容器起来了但数据库还没 ready,测试会随机失败(flaky)
fail-fast: false 默认 true 会在第一个版本失败时砍掉其余,你就看不到"到底是版本问题还是代码问题"
if: always() 测试失败了日志和报告最有价值,默认行为会在失败时跳过后续步骤
cancel-in-progress: true CI 用它省钱;部署场景要设 false
concurrency: group: ci-${{ github.ref }} 保证取消的是同一分支,不会误杀其他分支的 CI

分支保护 :到 Settings → Branches → Add branch protection rule,勾选 Require status checks to pass ,选中 test。这样 PR 测试挂了就不能合并------这是 CI 真正发挥作用的地方。


场景 4:Monorepo → 只构建改动的包(paths 过滤 + Turborepo)

Monorepo 最大的痛:改一个包,所有包都构建,CI 跑 40 分钟。

yaml 复制代码
name: CI (Monorepo)

on:
  push:
    branches: [main]
  pull_request:

jobs:
  changes:
    runs-on: ubuntu-latest
    outputs:
      web: ${{ steps.filter.outputs.web }}
      server: ${{ steps.filter.outputs.server }}
    steps:
      - uses: actions/checkout@v6
      # 用 paths-filter 判断"哪几个子项目变了",结果作为 outputs 传给下游
      - uses: dorny/paths-filter@v3
        id: filter
        with:
          filters: |
            web:
              - 'apps/web/**'
              - 'packages/ui/**'
              - 'pnpm-lock.yaml'
            server:
              - 'apps/server/**'
              - 'packages/shared/**'
              - 'pnpm-lock.yaml'

  build-web:
    needs: changes
    if: needs.changes.outputs.web == 'true'    # 没变就整个 job 跳过
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: pnpm/action-setup@v4
        with: { version: 9 }
      - uses: actions/setup-node@v4
        with: { node-version: 20, cache: pnpm }
      - run: pnpm install --frozen-lockfile
      - run: pnpm turbo run build --filter=web...

  build-server:
    needs: changes
    if: needs.changes.outputs.server == 'true'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: pnpm/action-setup@v4
        with: { version: 9 }
      - uses: actions/setup-node@v4
        with: { node-version: 20, cache: pnpm }
      - run: pnpm install --frozen-lockfile
      - run: pnpm turbo run build --filter=server...

三种"只跑相关任务"的粒度(按成本从低到高):

方式 写法 粒度 适用
工作流级 on.push.paths: ['apps/web/**'] 整个工作流 一个工作流只管一个包,最简单
作业级 dorny/paths-filter + needs + if 单个作业 本场景,最常用
任务级 Turborepo / Nx 内置远端缓存 单个任务 大型 monorepo,配合 TURBO_TOKEN 远端缓存效果最好

补一句 Turborepo 远端缓存的配置(能再省一半时间):

yaml 复制代码
      - run: pnpm turbo run build
        env:
          TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}   # 在 Vercel 上开 Turbo 远端缓存后生成
          TURBO_TEAM: ${{ vars.TURBO_TEAM }}        # vars 用于非敏感配置,secrets 用于密钥

vars vs secrets 的区别:vars 明文可见、可在日志里打印,适合 team 名、环境名;secrets 加密不可读,适合 token。两者都在 Settings → Secrets and variables → Actions 里配。


场景 5:Docker 构建并推送到 GHCR(GitHub 自带镜像仓库)

后端/全栈的标准发布流程 :打 tag → 构建镜像 → 推到 ghcr.io。

yaml 复制代码
name: Docker Publish

on:
  push:
    tags: ['v*.*.*']            # 只有打 tag(如 v1.2.0)才发布
  workflow_dispatch:

permissions:
  contents: read
  packages: write               # 推 GHCR 必须

jobs:
  build-push:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      # 让 docker 构建支持多架构、以及内联缓存
      - uses: docker/setup-buildx-action@v3

      - name: 登录 GHCR
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}   # 内置 token,不用自己建

      # 自动根据 git tag / 分支生成镜像 tag(语义化标签),别手写
      - name: 生成镜像标签
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ghcr.io/${{ github.repository }}
          tags: |
            type=semver,pattern={{version}}
            type=semver,pattern={{major}}.{{minor}}
            type=sha,prefix=sha-

      - name: 构建并推送
        uses: docker/build-push-action@v6
        with:
          context: .
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          cache-from: type=gha    # 用 GitHub Actions 缓存层,二次构建快 5~10 倍
          cache-to: type=gha,mode=max

为什么这么配

配置 原因
secrets.GITHUB_TOKEN 每个仓库自动生成、自动续期、权限可限,不需要你去建 PAT
docker/metadata-action 打 v1.2.0 标签会同时生成 1.2.0、1.2、sha-abc123 等多个 tag,回滚方便
cache-from: type=gha 不配的话每次全量重建镜像,几分钟变几秒的差别
packages: write 少了这行推镜像报 denied
tags: ['v*.*.*'] 只在正式版本发布,避免每次 push 都推镜像污染 registry

私有镜像拉取 :部署服务器要用 docker login ghcr.io -u <user> --password-stdin,密码用 PAT(含 read:packages)。


场景 6:部署到自己的服务器(SSH + rsync)

没有云平台、只有一台 VPS 的常见做法。

yaml 复制代码
name: Deploy to VPS

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production        # 可配置需要人工审批
    steps:
      - uses: actions/checkout@v6

      - uses: pnpm/action-setup@v4
        with: { version: 9 }
      - uses: actions/setup-node@v4
        with: { node-version: 20, cache: pnpm }
      - run: pnpm install --frozen-lockfile
      - run: pnpm build

      # 1) 把构建产物传到服务器(增量同步,--delete 保证一致性)
      - name: 同步文件
        uses: burnett01/rsync-deployments@7.0.1
        with:
          switches: -avzr --delete
          path: dist/
          remote_path: /var/www/myapp/
          remote_host: ${{ secrets.SSH_HOST }}
          remote_user: ${{ secrets.SSH_USER }}
          remote_key: ${{ secrets.SSH_PRIVATE_KEY }}

      # 2) 在服务器上重启服务
      - name: 重启服务
        uses: appleboy/ssh-action@v1
        with:
          host: ${{ secrets.SSH_HOST }}
          username: ${{ secrets.SSH_USER }}
          key: ${{ secrets.SSH_PRIVATE_KEY }}
          script: |
            cd /var/www/myapp
            pm2 restart myapp || pm2 start server.js --name myapp
            echo "deployed at $(date)"

SSH 密钥怎么配(新手最卡的一步):

bash 复制代码
# 本地生成专用密钥(不要用你日常登录的那把)
ssh-keygen -t ed25519 -C "github-actions-deploy" -f ./deploy_key -N ""

# 公钥放到服务器
ssh-copy-id -i ./deploy_key.pub user@your-server

# 私钥内容(含 BEGIN/END 行)整段贴到 Secret: SSH_PRIVATE_KEY
cat ./deploy_key

关键认知:一次性配置好就不要再动它。 这个私钥等于服务器的一部分门钥匙,只给这一个仓库用。

更现代的替代方案:用云厂商的 OIDC(AWS / GCP / Azure),不存长期密钥:

yaml 复制代码
permissions:
  id-token: write
  contents: read
steps:
  - uses: aws-actions/configure-aws-credentials@v4
    with:
      role-to-assume: arn:aws:iam::123456789:role/github-actions
      aws-region: ap-northeast-1

好处:没有任何长期密钥存在 GitHub 里,泄露风险大幅下降。新项目优先选这个。


场景 7:PR 自动化 → 自动打标签 / 评论 / 卡住超大 PR

团队协作里"省人力"的一类配置,通常一个文件管多件事。

yaml 复制代码
name: PR Automation

on:
  pull_request_target:            # 注意:不是 pull_request,见下方解释
    types: [opened, synchronize]

permissions:
  contents: read
  pull-requests: write

jobs:
  label:
    runs-on: ubuntu-latest
    steps:
      # 按改动文件路径自动打标签
      - uses: actions/labeler@v5
        with:
          repo-token: ${{ secrets.GITHUB_TOKEN }}

      # 按改动行数打 size/XS ~ size/XL 标签
      - uses: pascalgn/size-label-action@v0.5.5
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

  # 首次贡献者自动欢迎 + 加 first-time-contributor 标签
  welcome:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/first-interaction@v1
        with:
          repo-token: ${{ secrets.GITHUB_TOKEN }}
          pr-message: '感谢你的第一个 PR!维护者会在 2 个工作日内 review 🎉'

配套 .github/labeler.yml:

yaml 复制代码
frontend:
  - changed-files:
      - any-glob-to-any-file: ['src/components/**', 'src/views/**']
docs:
  - changed-files:
      - any-glob-to-any-file: ['docs/**', '**/*.md']
ci:
  - changed-files:
      - any-glob-to-any-file: ['.github/**']

⚠️ pull_request vs pull_request_target 是最容易出安全事故的一处:

  • pull_request:来自 fork 的 PR 拿不到 secrets,安全但做不了需要密钥的事。
  • pull_request_target:在目标仓库上下文 运行,能拿到 secrets ------ 所以绝对不要在这个工作流里 checkout 并执行 PR 的代码,否则等于把密钥交给陌生人。
  • 只打标签、发评论这类"不执行 PR 代码"的操作,用 pull_request_target 才安全;要跑 PR 的代码,就用 pull_request。

场景 8:定时任务 → 每天自动抓数据并提交回仓库

schedule 用 cron,但 GitHub 的 cron 有几个坑。

yaml 复制代码
name: Daily Data Sync

on:
  schedule:
    # 每天 01:00 UTC = 北京时间 09:00
    - cron: '0 1 * * *'
  workflow_dispatch:            # 一定要留手动触发口子,方便调试

permissions:
  contents: write               # 需要写回仓库

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
        with:
          persist-credentials: true

      - uses: actions/setup-node@v4
        with: { node-version: 20 }

      - name: 抓取数据
        run: node scripts/fetch-data.mjs

      - name: 有变化才提交
        run: |
          git config user.name  "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          if [[ -n "$(git status --porcelain)" ]]; then
            git add .
            git commit -m "chore: auto sync data $(date -u +%F)"
            git push
          else
            echo "无变化,跳过"
          fi

cron 的 4 个坑

坑 说明
时区 GitHub cron 一律 UTC,北京时间要减 8 小时(09:00 北京 = 01:00 UTC)
不是精确时间 高峰期可能延迟 10~30 分钟甚至更久。别用 cron 做秒级/分钟级的事
最短间隔 5 分钟 */1 * * * * 会被拒绝或静默忽略
60 天无提交会停用 仓库 60 天没活动,定时工作流会被自动禁用,需要手动重新启用(或定期提交一次保持活跃)

另外:git push 到受保护分支会被拦;需要走 PR 的话,用 peter-evans/create-pull-request 这个 Action 代替裸 git push。


场景 9:打 tag 自动发布(GitHub Release + npm publish)

开源库的标准发布流程。

yaml 复制代码
name: Release

on:
  push:
    tags: ['v*.*.*']

permissions:
  contents: write       # 创建 Release
  id-token: write       # npm provenance(供应链证明,强烈建议)

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0             # changelog 生成需要完整历史

      - uses: pnpm/action-setup@v4
        with: { version: 9 }
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: pnpm
          registry-url: https://registry.npmjs.org

      - run: pnpm install --frozen-lockfile
      - run: pnpm build
      - run: pnpm test -- --run

      # 用 tag 与上一个 tag 之间的 commit 自动生成发布说明
      - name: 创建 GitHub Release
        uses: softprops/action-gh-release@v2
        with:
          generate_release_notes: true

      # --provenance 会生成可验证的来源证明,是 npm 供应链安全的关键
      - name: 发布到 npm
        run: npm publish --provenance --access public
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

版本号必须与 tag 一致 :v1.2.0 的 tag 必须对应 package.json 里的 "version": "1.2.0",否则 npm 会拒绝(或用 automation token 覆盖)。 推荐加一步校验,避免手滑:

yaml 复制代码
      - name: 校验 tag 与 package.json 版本一致
        run: |
          PKG=$(node -p "require('./package.json').version")
          TAG=${GITHUB_REF_NAME#v}
          [ "$PKG" = "$TAG" ] || { echo "❌ tag=$TAG 但 package.json=$PKG"; exit 1; }

场景 10:多个仓库复用同一套 CI(可复用工作流)

公司有 5 个前端项目,CI 逻辑一模一样。别复制 5 份,抽成一个可复用工作流。

① 在公共仓库 .github/workflows/frontend-ci.yml 里定义模板:

yaml 复制代码
on:
  workflow_call:                    # ← 关键:表示"这个工作流是给别人调用的"
    inputs:
      node-version:
        type: number
        default: 20
      working-directory:
        type: string
        default: '.'
      run-e2e:
        type: boolean
        default: false
    secrets:
      NPM_TOKEN:
        required: false

jobs:
  ci:
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: ${{ inputs.working-directory }}
    steps:
      - uses: actions/checkout@v6
      - uses: pnpm/action-setup@v4
        with: { version: 9 }
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ inputs.node-version }}
          cache: pnpm
          cache-dependency-path: ${{ inputs.working-directory }}/pnpm-lock.yaml
      - run: pnpm install --frozen-lockfile
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
      - run: pnpm lint && pnpm typecheck && pnpm test -- --run
      - if: ${{ inputs.run-e2e }}
        run: pnpm test:e2e

② 在各业务仓库里调用(只有 10 行):

yaml 复制代码
# .github/workflows/ci.yml
name: CI
on: [push, pull_request]

jobs:
  call-ci:
    uses: my-org/shared-workflows/.github/workflows/frontend-ci.yml@main
    with:
      node-version: 20
      working-directory: apps/web
      run-e2e: false
    secrets:
      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

注意两点

  1. 被调用的工作流必须在公共仓库里、且该仓库可被访问。私有仓库跨仓库调用,需要在公共仓库的 Actions 设置里允许访问。
  2. uses: org/repo/.github/workflows/x.yml@main 中的 @main 生产环境建议改成 具体 commit SHA 或 tag,防止上游改动影响下游。

场景汇总对照表

场景 触发 关键配置 难度
1 前端 → Pages push: main permissions: pages/id-token + 双 job ★★
2 前端 → Vercel push / pull_request secrets + 环境区分 ★★
3 后端 CI push / pull_request matrix + services + concurrency ★★★
4 Monorepo pull_request paths-filter + needs + if ★★★★
5 Docker 镜像 push: tags permissions: packages + cache: gha ★★★
6 部署 VPS push: main SSH 密钥 + environment ★★★
7 PR 自动化 pull_request_target pull-requests: write + labeler.yml ★
8 定时任务 schedule + UTC contents: write + 变更才提交 ★★
9 发布 npm push: tags --provenance + generate_release_notes ★★★
10 复用工作流 workflow_call inputs / secrets 声明 ★★★★

通用安全加固清单(上生产前过一遍)

  • 每个工作流都写 permissions:,只给最小必要权限(默认可能过宽)。

  • 敏感信息一律走 secrets ,永不写进 yml、永不 echo 出来。

  • 第三方 Action 固定到 commit SHA ,不要用 @main:

    yaml 复制代码
    uses: some/action@8f4b7f84864484a7bf31766abe9204da3cbe65b3  # v2.3.1

    理由是 tag 可以被作者改指向,SHA 不能。

  • PR 工作流永远不执行不可信代码(见场景 7 的提示)。

  • 生产部署加 environment: production,配人工审批(Settings → Environments)。

  • 加 timeout-minutes ,防止卡死烧光额度:jobs.<id>.timeout-minutes: 15。

  • 优先用 OIDC 代替长期密钥(AWS/GCP/Azure 都已支持)。


10. 进阶路线:接下来学什么

按这个顺序学,坡度最缓:

第一层:把骨架用熟

  1. on: 的各种事件与过滤 ------ 触发工作流
  2. needs: 让作业串起来,形成"构建 → 测试 → 部署"流水线
  3. env / secrets 管理环境变量和密钥(密钥千万别写死在 yml 里)
  4. if: 条件执行;strategy: matrix 一次跑多个版本组合

第二层:真实项目 5. 构建和测试代码 ------ 最实用的 CI 6. 发布包 7. 部署到第三方平台 8. 缓存依赖加速(actions/cache)、上传测试报告(artifact)

第三层:工程化 9. 复用工作流(workflow_call)和自定义 Action 10. 自托管运行器、大型运行器 11. 权限最小化(permissions:)、第三方 Action 固定 SHA


11. 附录:速查表与术语表

11.1 最小可用工作流模板(直接抄走)

yaml 复制代码
name: CI
on:
  push:
    branches: [main]
  pull_request:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: 拉取代码
        uses: actions/checkout@v6

      - name: 安装 Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm

      - name: 安装依赖
        run: npm ci

      - name: 跑测试
        run: npm test

11.2 常用键速查

| 键 | 作用 |
|-----------------------------|-------------------------------------------|----------|
| name | 工作流名称 |
| run-name | 单次运行显示名 |
| on | 触发事件(可带 branches / paths / cron 过滤) |
| jobs.<id> | 定义一个作业(ID 自定义) |
| jobs.<id>.runs-on | 用哪种运行器 |
| jobs.<id>.needs | 依赖哪些作业先完成 |
| jobs.<id>.if | 满足条件才执行 |
| jobs.<id>.env | 作业级环境变量 |
| jobs.<id>.steps[].name | 步骤显示名 |
| jobs.<id>.steps[].run | 执行 shell 命令(` | ` 支持多行) |
| jobs.<id>.steps[].uses | 调用 Action(格式 owner/repo@version) |
| jobs.<id>.steps[].with | 传给 Action 的参数 |
| jobs.<id>.strategy.matrix | 矩阵:一次跑多组变量 |
| timeout-minutes | 超时保护,防止卡死烧额度 |

11.3 术语表

  • CI/CD:持续集成 / 持续交付部署,自动化构建测试发布的实践。
  • Workflow(工作流):一个 YAML 定义的自动化流程。
  • Event(事件):触发工作流的仓库活动。
  • Job(作业):工作流中的一个任务单元,独占一台运行器。
  • Step(步骤) :作业中的最小单元,run 命令或 uses 动作。
  • Runner(运行器):执行作业的机器,GitHub 免费提供托管虚拟机,也可自托管。
  • Action(动作) :可复用的自动化模块,可从 Marketplace 获取。
  • Artifact(产物):作业产生的文件(日志、构建包、测试报告),可在运行间传递与下载。
  • Context(上下文) :${{ }} 中可用的变量集合,如 github、env、job、secrets、matrix。
  • Secret(密钥) :加密存储的敏感变量,运行时通过 ${{ secrets.NAME }} 引用。

一句话总结

在 .github/workflows/ 放一个 .yml,声明"什么事件触发(on)→ 在哪台机器跑(runs-on)→ 依次做哪些事(steps)",GitHub 就会在每次事件发生时,免费起一台干净虚拟机,把代码拉下来(checkout)、按顺序执行你的命令,并把日志摊给你看。

相关推荐
广州华水科技32 分钟前
单北斗GNSS变形监测系统在大坝安全维护中的重要性
前端
anyup33 分钟前
自带 uni-app x 页面级能力,uView Pro X 8 个开箱即用的工具函数
前端·vue.js·uni-app
涛涛ing1 小时前
别拿 Chrome 跑通了就提测:把这段 AI 写的代码发到 Safari 上,我差点丢了工作
前端
墨林陌1 小时前
用 AI 给娃做了一个识物游戏:一份 2.3MB 的单文件 HTML,126 张卡片、三种玩法,手机平板打开就能玩
前端
Hilaku1 小时前
Claude Code 过夜跑长任务实战:tmux、权限、验收,以及我为什么换到 ApexOne
前端·javascript·程序员
程序员大阳1 小时前
副队长ES6+教程(14)--手写Promise来加深理解
前端·javascript·es6·源码·promise·手写·深层
J船长1 小时前
从 Trellis 看 AI 研发工具选型:OpenSpec、Spec Kit 与 Harness 如何配合
前端
对象存储与RustFS2 小时前
对象锁遇上版本化:删掉的对象还在,真删的又删不掉
后端·docker·云原生
FungLeo2 小时前
成为全栈·Vue 管理后台篇·可折叠侧栏与移动抽屉:后台导航的响应式实现
前端·javascript·vue.js·侧边栏·响应式布局·无障碍·移动端导航