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

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

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

---

1. 什么是 GitHub Actions？

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

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

在我们的场景中，Actions 会：

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

---

2. 新建工作流文件

在你的项目根目录下创建目录和文件：

.github/workflows/deploy.yml

然后将以下配置写入：

# 工作流名称
name: Build and Deploy# 触发条件
on:# 当 develop 分支有代码推送时触发push:branches:- develop# 一个 workflow 可以包含多个 job
jobs:# job 唯一 keybuild-and-deploy:# 运行环境runs-on: ubuntu-latest# job 内的步骤steps:# 1. 拉取仓库代码- name: Checkout  ️uses: actions/checkout@v2.3.1# 2. 安装指定版本 Node.js- name: lock npm versionuses: actions/setup-node@v3with:node-version: 18.18.0# 3. 安装依赖并构建- name: Install and Buildrun: |npm i -g pnpmpnpm run initpnpm run docs:buildenv:NODE_OPTIONS: '--max_old_space_size=4096'# 4. 部署到 GitHub Pages- name: Deployuses: JamesIves/github-pages-deploy-action@4.1.3with:BRANCH: gh-pagesFOLDER: docs/.vuepress/distACCESS_TOKEN: ${{ secrets.ACCESS_TOKEN }}

---

3. 配置详解

① 触发条件

on:push:branches:- develop

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

---

② 检出代码

uses: actions/checkout@v2.3.1

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

---

③ 安装 Node.js

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

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

---

④ 构建 VuePress

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

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

这里额外加了：

env:NODE_OPTIONS: '--max_old_space_size=4096'

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

---

⑤ 部署到 GitHub Pages

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。

步骤：

1. 打开 GitHub → Settings → Developer settings → Personal Access Tokens

2. 点击 Generate new token

3. 勾选 repo 权限，生成 Token

4. 回到仓库 → Settings → Secrets and variables → Actions
   点击 New repository secret：

   • Name：ACCESS_TOKEN
   • Value：刚刚生成的 Token

5. 保存

---

5. 流程示意

---

6. 效果

现在只需要：

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

GitHub Actions 会在云端帮你完成：

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

---

7. 总结

这次我们实现了：

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

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

---

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