使用 Vuepress + GitHub Pages 搭建项目文档（2）- 使用 GitHub Actions 工作流自动部署

在上一篇文章中，我们已经成功用 VuePress 搭建了项目文档，并使用 sh 脚本部署到了 GitHub Pages 。但随着文档的更新频率增加，每次都要手动推送，那有没有不需要手动推送的方法呢？那必须有。

这次我们将用 GitHub Actions 实现"代码一提交，文档自动上线"的全流程自动化部署。

1. 什么是 GitHub Actions？

GitHub Actions 是 GitHub 提供的 CI/CD（持续集成与持续交付）平台，支持：

根据触发条件（push、PR、定时等）执行任务
在云端虚拟机上自动构建、测试、部署
免去本地手动操作，降低出错率

在我们的场景中，Actions 会：

检测到代码更新
在云端安装依赖并构建 VuePress
将静态文件部署到 gh-pages 分支
自动更新 GitHub Pages 网站

2. 新建工作流文件

bash 复制代码

.github/workflows/deploy.yml

然后将以下配置写入：

yaml 复制代码

# 工作流名称
name: Build and Deploy

# 触发条件
on:
    # 当 develop 分支有代码推送时触发
    push:
        branches:
            - develop

# 一个 workflow 可以包含多个 job
jobs:
    # job 唯一 key
    build-and-deploy:
        # 运行环境
        runs-on: ubuntu-latest

        # job 内的步骤
        steps:
            # 1. 拉取仓库代码
            - name: Checkout  ️
              uses: actions/checkout@v2.3.1

            # 2. 安装指定版本 Node.js
            - name: lock npm version
              uses: actions/setup-node@v3
              with:
                  node-version: 18.18.0

            # 3. 安装依赖并构建
            - name: Install and Build
              run: |
                  npm i -g pnpm
                  pnpm run init
                  pnpm run docs:build
              env:
                  NODE_OPTIONS: '--max_old_space_size=4096'

            # 4. 部署到 GitHub Pages
            - name: Deploy
              uses: JamesIves/github-pages-deploy-action@4.1.3
              with:
                  BRANCH: gh-pages
                  FOLDER: docs/.vuepress/dist
                  ACCESS_TOKEN: ${{ secrets.ACCESS_TOKEN }}

3. 配置详解

① 触发条件

yaml 复制代码

on:
  push:
    branches:
      - develop

当 develop 分支有新提交时，工作流就会运行。如果你希望直接监听 master，改成 - master 即可。

② 检出代码

yaml 复制代码

uses: actions/checkout@v2.3.1

把当前分支的代码拉取到 GitHub 提供的运行环境中，方便后续构建。

③ 安装 Node.js

yaml 复制代码

uses: actions/setup-node@v3
with:
    node-version: 18.18.0

指定 Node.js 版本，保证构建环境和本地一致，避免版本差异引起的 bug。

④ 构建 VuePress

bash 复制代码

npm i -g pnpm
pnpm run init
pnpm run docs:build

全局安装 pnpm
执行 init（通常是安装依赖的命令）
执行 VuePress 的构建命令，生成静态文件到 docs/.vuepress/dist

这里额外加了：

yaml 复制代码

env:
    NODE_OPTIONS: '--max_old_space_size=4096'

调高 Node.js 最大内存限制，避免文档量大时构建内存不足。

⑤ 部署到 GitHub Pages

yaml 复制代码

uses: JamesIves/github-pages-deploy-action@4.1.3

这是社区常用的部署 Action，可以自动将构建后的静态文件推送到指定分支（这里是 gh-pages）。

参数：

BRANCH：目标分支（GitHub Pages 会从这里拉取文件）
FOLDER：静态文件目录
ACCESS_TOKEN：有推送权限的 Token（放在仓库的 Secrets 中）

4. 配置 ACCESS_TOKEN

为了让 GitHub Actions 能推送到 gh-pages 分支，我们需要一个具有写权限的 Personal Access Token。

步骤：

打开 GitHub → Settings → Developer settings → Personal Access Tokens
点击 Generate new token
勾选 repo 权限，生成 Token
回到仓库 → Settings → Secrets and variables → Actions 点击 New repository secret：
- Name：ACCESS_TOKEN
- Value：刚刚生成的 Token
保存

5. 流程示意

flowchart TD A[推送代码到 develop 分支] --> B[触发 GitHub Actions] B --> C[拉取代码 Checkout] C --> D[安装 Node.js 和 pnpm] D --> E[构建 VuePress 文档] E --> F[部署到 gh-pages 分支] F --> G[GitHub Pages 自动更新]

6. 效果

现在只需要：

bash 复制代码

git add .
git commit -m "更新文档"
git push origin develop

GitHub Actions 会在云端帮你完成：

构建文档
部署到 GitHub Pages
几十秒后网站自动更新 🎉

7. 总结

这次我们实现了：

监听分支变化
云端构建 VuePress
自动部署到 GitHub Pages

整个过程无需手动切分支、build、推送，大幅提高了效率。

如果你觉得这篇文章对你有帮助，欢迎点赞、收藏或留言交流 😊