GitHub Actions 入门

GitHub Actions 是 GitHub 内置的 CI/CD 平台，通过 YAML 配置自动化工作流。

这页更适合当作“团队自动化起步手册”来用：先把持续集成跑通，再决定是否把部署、发版、定时任务也收进仓库。很多仓库一开始就把 CI/CD 全塞进一个工作流，后面往往会变成难改、难排障、改一个步骤全局受影响。

推荐落地顺序

建议按下面的顺序逐步接入，而不是一次写满所有能力：

1. 先做最小 CI：安装依赖、类型检查、测试、构建
2. 再加缓存与矩阵测试，提升速度和兼容性
3. 然后拆出部署工作流，避免与 CI 混在一起
4. 最后再补 Release、定时任务、自动清理等辅助流程

如果项目已经接入平台自带的 Git 自动部署（例如 Cloudflare Pages / Vercel / Netlify），那 GitHub Actions 往往更适合负责“检查与门禁”，而不是重复做第二次部署。

工作流拆分建议

常见的目录结构如下：

.github/workflows/
  ci.yml            # lint / test / build
  deploy.yml        # 部署到服务器或平台
  release.yml       # tag / release note / artifact
  nightly.yml       # 定时任务、巡检、备份

拆分的核心好处有两个：

• 改测试流程时，不会误伤部署逻辑
• 出问题时能快速判断是“质量检查失败”还是“发布链路失败”

基本结构

在仓库中创建 .github/workflows/ci.yml：

name: CI

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

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm ci
      - run: npm run build
      - run: npm test

触发条件

on:
  push:
    branches: [main, develop]
    paths:
      - "src/**"
      - "package.json"
  pull_request:
    branches: [main]
  schedule:
    - cron: "0 0 * * 1" # 每周一 UTC 0:00
  workflow_dispatch: # 手动触发

常用模板

Node.js 项目

name: CI
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [20, 22]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
      - uses: pnpm/action-setup@v4
        with:
          version: latest
      - run: pnpm install --frozen-lockfile
      - run: pnpm lint
      - run: pnpm test
      - run: pnpm build

部署到 Cloudflare Pages

name: Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - uses: pnpm/action-setup@v4
        with:
          version: latest
      - run: pnpm install --frozen-lockfile
      - run: pnpm build
      - uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          command: pages deploy dist --project-name=my-project

Docker 构建推送

name: Docker
on:
  push:
    tags: ["v*"]

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: docker/setup-buildx-action@v3
      - uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - uses: docker/build-push-action@v6
        with:
          push: true
          tags: ghcr.io/${{ github.repository }}:${{ github.ref_name }}

自动发布 Release

name: Release
on:
  push:
    tags: ["v*"]

jobs:
  release:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v4
      - uses: softprops/action-gh-release@v2
        with:
          generate_release_notes: true

Secrets 配置

仓库 Settings → Secrets and variables → Actions → New repository secret

在工作流中使用：

env:
  API_KEY: ${{ secrets.API_KEY }}

缓存依赖

- uses: actions/cache@v4
  with:
    path: ~/.pnpm-store
    key: pnpm-${{ hashFiles('pnpm-lock.yaml') }}
    restore-keys: pnpm-

权限与 Secrets 建议

Secrets 能不用就不用，必须用时也尽量最小化权限。

permissions:
  contents: read

常见经验：

• 纯测试工作流通常只需要只读权限
• 需要发 Release、写评论、推镜像时，再按需加 contents: write、packages: write
• 把密钥分仓库环境管理，例如 preview、production，不要所有环境共用一套
• 部署前先确认 Secret 名称、作用域和环境是否一致

Cloudflare Pages 场景提醒

如果你已经把仓库直接绑定到 Cloudflare Pages，那么：

• push 到指定分支后，Pages 会自动拉代码并构建部署
• 这时 GitHub Actions 更适合做 lint、test、build 预检查
• 除非你明确需要“手动部署某个产物目录”或“多环境发布”，否则没必要再在 Actions 里额外执行一次 pages deploy

简单说：平台自动部署负责上线，Actions 负责兜底检查，这通常比“双重部署源”更清晰。

常用 Actions

常见失败排查

依赖安装失败

• 先确认锁文件是否提交，例如 pnpm-lock.yaml、package-lock.json
• 再确认工作流里使用的包管理器是否和本地一致
• Node.js 版本、pnpm 版本不一致时，也很容易出现“本地能过，CI 失败”

构建失败但本地正常

• 检查是否遗漏了环境变量
• 检查构建命令是否依赖本地特有文件或缓存
• 检查 Linux 大小写敏感问题，例如 import './Utils' 与真实文件名不一致

部署成功但线上异常

• 先确认部署的到底是不是最新 commit
• 再确认产物目录是否正确，例如 dist、.output/public、build
• 如果平台本身有 Git 自动部署，避免 Actions 再单独部署旧产物

工作流重复执行

同一个仓库同时配置了 push、pull_request、平台自动构建时，很容易出现“看起来像重复跑三次”的情况。需要提前明确：

• 谁负责质量检查
• 谁负责真正上线
• 哪个分支触发预览，哪个分支触发生产部署

延伸阅读

• Git 安装与配置
• Docker Desktop 安装与使用
• 本地开发环境搭建
• 监控与日志

参考链接

• GitHub Actions 文档 — 官方文档
• Actions 市场 — 搜索 Actions
• Workflow 语法 — 完整语法参考