GitHub Actions 自动化部署实战：推送代码自动上线

每次改完代码，手动 scp 上传、手动重启服务、手动清缓存……一套流程走下来，改一行 CSS 也要折腾 5 分钟。更别提哪天手滑把测试环境的代码推到生产环境了。GitHub Actions 就是来解决这个问题的——代码推上去，剩下的它全自动搞定，你甚至可以躺着用手机写代码然后坐等上线。

GitHub Actions 是什么？

GitHub Actions 是 GitHub 内置的 CI/CD 服务。你在仓库里写一个 YAML 配置文件，定义好"什么时候触发"和"做什么事"，GitHub 就免费提供虚拟机帮你跑。

公开仓库无限免费使用，私有仓库每月 2000 分钟免费额度，个人项目根本用不完。

一、核心概念

GitHub Actions 有几个关键概念，搞清楚了写配置文件才不会晕：

二、你的第一个 Workflow

在仓库根目录创建 .github/workflows/deploy.yml：

name: Deploy to GitHub Pages

# 触发条件：推送到 main 分支时触发
on:
  push:
    branches:
      - main

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest      # 用最新的 Ubuntu 虚拟机

    steps:
      # 步骤1：拉取代码
      - name: Checkout
        uses: actions/checkout@v4

      # 步骤2：安装 Node.js
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20

      # 步骤3：安装依赖
      - name: Install Dependencies
        run: npm install

      # 步骤4：构建项目
      - name: Build
        run: npm run build

      # 步骤5：部署
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./dist

把这个文件推到仓库，以后每次 git push，GitHub 就会自动跑这 5 个步骤。

三、触发器详解

除了 push，还有很多触发方式：

# 推到 main 分支
on:
  push:
    branches: [main]

# 发 PR 到 main 时跑测试
on:
  pull_request:
    branches: [main]

# 每天凌晨 3 点自动跑（UTC 时间）
on:
  schedule:
    - cron: '0 3 * * *'

# 手动触发（在 GitHub 网页上点按钮）
on:
  workflow_dispatch:

# 多个事件组合
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

schedule 用的是 POSIX cron 语法，跟 Linux crontab 一样。注意时区是 UTC，北京时间要减 8 小时。

四、实战：Hexo 博客自动部署到 GitHub Pages

假设你有一个 Hexo 博客，源文件放在 source 分支，生成后的静态文件部署到 main 分支的 Pages。

.github/workflows/hexo-deploy.yml：

name: Hexo Deploy

on:
  push:
    branches:
      - source       # 源文件分支

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          ref: source

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

      - name: Cache node_modules
        uses: actions/cache@v4
        with:
          path: node_modules
          key: ${{ runner.os }}-node-${{ hashFiles('package-lock.json') }}

      - run: npm install
      - run: npx hexo generate

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_branch: main      # 部署到 main 分支
          publish_dir: ./public
          force_orphan: true

这里面用了一个 actions/cache@v4，它能把 node_modules 缓存起来，下次构建不用重新 npm install，速度从 2 分钟缩短到 20 秒。

五、实战：自动跑测试，不通过不让合代码

没人 review 的小项目最怕改了一个地方、坏了三个地方。用 Actions 在每次 PR 时自动跑测试：

name: Run Tests

on:
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - run: pip install -r requirements.txt
      - run: pytest --cov=./ --cov-report=xml

然后在仓库 Settings → Branches → Branch protection rules，勾选 "Require status checks to pass before merging"，把 test 这个 Job 加上。

从此以后，测试不通过的 PR 没法合进 main 分支。

六、用 Secrets 管理敏感信息

数据库密码、SSH 私钥、API Token 这些东西绝对不能写在 YAML 里。用 GitHub Secrets：

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

在 Workflow 中这样引用：

- name: Deploy to server
  uses: appleboy/ssh-action@v1
  with:
    host: ${{ secrets.SERVER_HOST }}
    username: ${{ secrets.SERVER_USER }}
    key: ${{ secrets.SSH_PRIVATE_KEY }}
    script: |
      cd /var/www/myapp
      git pull
      docker compose up -d --build

这样就算有人看到了你的 Workflow 文件，也拿不到真正的密钥。

七、矩阵构建：一次测多个环境

你的项目要同时支持 Python 3.10、3.11、3.12？用矩阵策略一次性全跑：

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ['3.10', '3.11', '3.12']
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}
      - run: pip install pytest
      - run: pytest

GitHub 会并行启动 3 个虚拟机，分别跑 3 个 Python 版本的测试。${{ matrix.python-version }} 会被替换成对应的版本号。

八、常用 Actions 速查

GitHub Actions 生态里有很多现成的 Action，不用自己写脚本：

GitHub Actions 就是你白嫖的 CI/CD 服务器。配置一次，以后只管写代码和 git push，测试、构建、部署全自动。回头看看之前手动 scp 上传的日子，你会觉得那时候的自己真是活在石器时代。