平时写一些 Vue Demo 或个人项目，为了方便展示，一般都会部署到 GitHub Pages。
以前我一直使用 gh-pages 手动部署，每次更新代码都要执行：
npm run build
npm run deploy虽然不算麻烦，但时间长了还是觉得效率不高。
后来换成了 GitHub Actions 自动部署 ，现在只要执行一次 git push，GitHub 就会自动完成项目构建、部署，全程无需手动操作。
本文记录一下完整的配置流程，以及我在配置过程中遇到的几个坑。
最终效果
整个流程如下：
修改代码
│
▼
git push
│
▼
GitHub Actions 自动运行
│
▼
安装依赖
│
▼
Vite 打包
│
▼
部署到 GitHub Pages
│
▼
网站自动更新以后更新网站，只需要正常提交代码即可。
一、修改 Vite 配置
打开 vite.config.js（或 vite.config.ts）。
增加 base 配置：
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
export default defineConfig({
plugins: [vue()],
base: '/taobao/',
})这里需要注意：
base: '/taobao/'其中 taobao 必须改成自己的 GitHub 仓库名称。
例如仓库叫：
my-demo那么应该写成：
base: '/my-demo/'否则部署之后页面可能会出现空白，或者 CSS、JavaScript 加载失败。
二、创建 GitHub Actions 工作流
在项目根目录创建：
.github
└── workflows
└── deploy.yml目录结构如下：
project
│
├── src
├── public
├── package.json
├── vite.config.js
└── .github
└── workflows
└── deploy.yml三、编写 deploy.yml
复制下面的配置即可。
注意： 目前 GitHub 已经逐步淘汰 Node.js 20，建议直接使用 Node.js 22。
name: Deploy Vite to GitHub Pages
on:
push:
branches:
- main
permissions:
contents: read
pages: write
id-token: write
concurrency:
group: pages
cancel-in-progress: true
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Setup Node
uses: actions/setup-node@v4
with:
node-version: 22
cache: npm
- name: Install Dependencies
run: npm install
- name: Build Project
run: npm run build
- name: Upload Pages Artifact
uses: actions/upload-pages-artifact@v3
with:
path: ./dist
deploy:
needs: build
runs-on: ubuntu-latest
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
permissions:
pages: write
id-token: write
steps:
- name: Deploy
id: deployment
uses: actions/deploy-pages@v4如果你使用的是 pnpm，把：
run: npm install修改为：
run: pnpm install同时：
run: npm run build修改成：
run: pnpm build即可。
四、开启 GitHub Pages
进入仓库：
Settings
↓
Pages找到：
Build and deployment将 Source 修改为：
GitHub Actions不要选择：
Deploy from a branch配置完成后保存即可。
如果看到类似下面的信息：
Your site is live at
https://用户名.github.io/仓库名/说明 Pages 已经配置成功。
五、提交代码
如果本地和远程都是 main 分支：
git add .
git commit -m "配置 GitHub Actions 自动部署"
git push origin main如果像我一样：
-
本地分支：
master -
GitHub 分支：
main -
GitHub 远程仓库名称：
github
则执行：
git add .
git commit -m "配置 GitHub Actions 自动部署"
git push github master:main这里的 master:main 表示：
将本地
master分支推送到 GitHub 的main分支。
GitHub Actions 监听的是 GitHub 仓库中的 main 分支，因此这种推送方式同样可以正常触发自动部署。
六、查看是否部署成功
代码推送完成后，进入仓库顶部：
Actions如果配置正确，会看到类似下面的工作流：
Deploy Vite to GitHub Pages正常情况下会经历：
Queued
↓
In progress
↓
Success最后所有步骤都会显示绿色。
例如：
✔ Checkout
✔ Setup Node
✔ Install Dependencies
✔ Build Project
✔ Upload Pages Artifact
✔ Deploy说明自动部署已经成功。
七、如何验证网站已经更新
建议第一次配置完成后，可以故意修改一个比较明显的地方，例如首页标题：
<h1>GitHub Actions 自动部署成功！</h1>提交代码：
git add .
git commit -m "测试自动部署"
git push github master:main等待几十秒后刷新网页。
如果页面内容已经更新，说明整套自动部署流程已经生效。
以后每次提交代码，网站都会自动更新。
八、我遇到的几个坑
1、base 配置错误
最常见的问题。
base: '/仓库名/'这里一定要和 GitHub 仓库名称保持一致。
否则页面容易白屏。
2、Pages Source 选择错误
第一次配置时，我选择的是：
Deploy from a branch导致 GitHub Actions 无法正常部署。
后来修改为：
GitHub Actions问题就解决了。
3、本地和远程分支名称不同
我的项目比较特殊：
-
Gitee 远程仓库叫
origin -
GitHub 远程仓库叫
github -
本地分支是
master -
GitHub 默认分支是
main
因此推送命令为：
git push github master:main开始还担心 GitHub Actions 不会触发。
后来发现，GitHub Actions 只关心 GitHub 仓库最终更新的是哪个分支，并不关心你本地分支叫什么。
只要最终更新的是 main，工作流就会自动执行。
总结
相比 gh-pages 手动部署，GitHub Actions 最大的优势就是自动化。
整个配置只需要完成一次，后续每次推送代码都会自动：
-
拉取最新代码
-
安装依赖
-
构建项目
-
部署到 GitHub Pages
整个过程完全不用人工干预。
对于 Vue、React、Vite 等静态项目来说，这也是目前比较推荐的一种部署方式。
如果你正在做个人博客、作品集或者 Demo 展示，不妨尝试一下 GitHub Actions，相信会比手动部署省心不少。