GitHub Action 进阶
约 1168 字大约 4 分钟
CI/CDGitHub ActionsDevOps
2026-04-16
GitHub Actions 简介
GitHub Actions 是 GitHub 提供的持续集成和持续部署(CI/CD)平台,允许你在 GitHub 仓库中自动构建、测试和部署代码。
核心概念
| 概念 | 说明 |
|---|---|
| Workflow | 整个自动化流程,定义在 .github/workflows/*.yml 文件中 |
| Job | 一个_job_是你同意在同一运行器上执行的一组步骤 |
| Step | 步骤,可以执行命令或使用 Action |
| Action | 可复用的动作单元,是 Workflow 的基本构建块 |
Workflow 文件结构
name: CI Workflow
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup Node
uses: actions/setup-node@v4
with:
node-version: '20'
- run: npm ci
- run: npm run build触发条件(on)
# 推送时触发
on: push
# 指定分支
on:
push:
branches:
- main
- develop
# PR 时触发
on: pull_request
# 定时触发 (cron 格式,UTC 时间)
on:
schedule:
- cron: '0 2 * * *' # 每天凌晨2点
# 手动触发
on:
workflow_dispatch:
inputs:
environment:
description: '部署环境'
required: true
default: 'staging'
# 仓库事件触发
on:
repository_dispatch:
types: [deploy-production]jobs 与 runs-on
jobs:
build:
runs-on: ubuntu-latest # GitHub 托管的运行器
# runs-on: self-hosted # 自托管运行器
test:
runs-on: ubuntu-latest
needs: build # 依赖 build job
deploy:
runs-on: ubuntu-latest
needs: [build, test] # 依赖多个 jobsteps 与 uses / run
steps:
# 使用 Action
- uses: actions/checkout@v4
# 使用 Action 并设置参数
- uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'npm'
# 执行命令
- name: Install dependencies
run: npm ci
# 多行命令
- name: Build
run: |
npm run lint
npm run build
# 设置输出供后续 step 使用
- id: version
run: echo "VERSION=$(npm pkg get version)" >> $GITHUB_OUTPUT环境变量与 Secrets
环境变量
env:
NODE_ENV: production
API_URL: https://api.example.com
jobs:
build:
env:
NODE_ENV: development
steps:
- run: echo ${{ env.NODE_ENV }}Secrets
在仓库 Settings → Secrets and variables → Actions 中配置敏感信息。
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Deploy
env:
API_TOKEN: ${{ secrets.API_TOKEN }}
DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}
run: |
curl -X POST https://api.example.com/deploy \
-H "Authorization: Bearer $API_TOKEN"条件执行
if 条件判断
jobs:
deploy:
runs-on: ubuntu-latest
steps:
# 仅在 main 分支推送时执行
- name: Deploy to production
if: github.ref == 'refs/heads/main' && github.event_name == 'push'
run: npm run deploy:prod
# 仅在 PR 时执行
- name: Preview deploy
if: github.event_name == 'pull_request'
run: npm run deploy:preview
# 基于步骤结果执行
- name: Notify
if: failure()
run: echo "Job failed!"matrix 并行矩阵
jobs:
test:
runs-on: ubuntu-latest
strategy:
matrix:
node-version: [18, 20, 22]
operating-system: [ubuntu-latest, windows-latest]
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: ${{ matrix.node-version }}
- run: npm ci
- run: npm test
# 失败时停止其他 job
build:
runs-on: ubuntu-latest
strategy:
matrix:
version: [12, 14, 16]
fail-fast: true缓存优化
actions/cache
steps:
- uses: actions/checkout@v4
- name: Cache node_modules
uses: actions/cache@v4
with:
path: node_modules
key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
restore-keys: |
${{ runner.os }}-node-npm/pnpm 依赖缓存
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'npm' # 自动缓存 node_modules
- run: npm ci# pnpm
- uses: pnpm/action-setup@v3
with:
version: 8
- uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'pnpm'
- run: pnpm install --frozen-lockfile常用 Action
actions/checkout
- uses: actions/checkout@v4
with:
fetch-depth: 0 # 完整克隆, 用于 git 操作
token: ${{ secrets.GITHUB_TOKEN }} # 自动获得actions/setup-node
- uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'npm' # npm/pnpm/yarn
cache-dependency-path: '**/package-lock.json'actions/cache
- uses: actions/cache@v4
with:
path: |
~/.npm
.next/cache
key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
restore-keys: |
${{ runner.os }}-node-peaceiris/actions-gh-pages
- name: Deploy to GitHub Pages
uses: peaceiris/actions-gh-pages@v4
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./dist
publish_branch: gh-pages前端项目完整 CI 流程示例
name: Frontend CI
on:
push:
branches: [main]
pull_request:
branches: [main]
env:
NODE_VERSION: '20'
jobs:
lint:
name: Lint
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: ${{ env.NODE_VERSION }}
cache: 'npm'
- run: npm ci
- run: npm run lint
test:
name: Test
runs-on: ubuntu-latest
needs: lint
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: ${{ env.NODE_VERSION }}
cache: 'npm'
- run: npm ci
- run: npm test -- --coverage
build:
name: Build
runs-on: ubuntu-latest
needs: test
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: ${{ env.NODE_VERSION }}
cache: 'npm'
- run: npm ci
- run: npm run build
- name: Upload build artifacts
uses: actions/upload-artifact@v4
with:
name: dist
path: dist
retention-days: 7
deploy:
name: Deploy
runs-on: ubuntu-latest
needs: build
if: github.ref == 'refs/heads/main'
steps:
- uses: actions/checkout@v4
- uses: peaceiris/actions-gh-pages@v4
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./dist进阶技巧
复用 Action
workflow_dispatch(手动触发)
on:
workflow_dispatch:
inputs:
tag:
description: '镜像版本'
required: true
type: string
environment:
description: '部署环境'
required: true
type: choice
options:
- staging
- production
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- name: Deploy
run: |
echo "Deploying ${{ github.event.inputs.tag }} to ${{ github.event.inputs.environment }}"触发方式:
gh workflow run deploy.yml -f tag=v1.0.0 -f environment=productionrepository_dispatch(外部触发)
on:
repository_dispatch:
types: [deploy-request]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Deploy
run: echo "Deploying..."外部触发(需 GitHub Token):
curl -X POST \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer $GITHUB_TOKEN" \
https://api.github.com/repos/$OWNER/$REPO/dispatches \
-d '{"event_type":"deploy-request","client_payload":{"environment":"prod"}}'并行任务优化
jobs:
# 独立的并行任务
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: npm ci
- run: npm run lint
type-check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: npm ci
- run: npm run type-check
# 依赖检查可以并行运行
dependency-audit:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: npm ci
- run: npm audit
# 只有所有检查通过后才构建
build:
runs-on: ubuntu-latest
needs: [lint, type-check, dependency-audit]
steps:
- uses: actions/checkout@v4
- run: npm ci
- run: npm run build使用 Concurrency 避免重复运行
on:
push:
branches: [main]
# 同一分支的新 push 会取消之前的 workflow
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
# ...