GitHub Actions 来发布一个 Vue 3 基础项目
概述
本节实践使用 GitHub Actions 将一个 Vue 3 基础项目自动构建并发布到 GitHub Pages。从配置 Node.js 环境、安装依赖、构建项目到部署发布，完成一个完整的 CI/CD 流程。
发布流程
Push 代码到 main 分支
↓
GitHub Actions 触发
↓
配置 Node.js 18 环境
↓
pnpm install 安装依赖
↓
pnpm build 构建项目
↓
部署到 GitHub Pages
text
Workflow 配置
完整 YAML 文件
# .github/workflows/deploy.yml
name: Deploy to GitHub Pages
on:
push:
branches: [main]
permissions:
contents: read
pages: write
id-token: write
jobs:
build-and-deploy:
runs-on: ubuntu-latest
steps:
# 步骤1：拉取代码
- name: Checkout
uses: actions/checkout@v4
# 步骤2：配置 Node.js 环境
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: 18
# 步骤3：安装 pnpm
- name: Setup pnpm
uses: pnpm/action-setup@v2
with:
version: 8
# 步骤4：安装依赖
- name: Install dependencies
run: pnpm install --frozen-lockfile
# 步骤5：构建项目
- name: Build
run: pnpm build
env:
VITE_BASE_URL: /${{ github.event.repository.name }}/
# 步骤6：部署到 GitHub Pages
- name: Deploy to GitHub Pages
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./dist
yaml
配置详解
Node.js 版本设置
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: 18 # 指定 Node.js 版本
yaml
pnpm 配置
- name: Setup pnpm
uses: pnpm/action-setup@v2
with:
version: 8
# pnpm 依赖缓存路径
# cache: 'pnpm' # 使用 cache 加速安装
# cache-dependency-path: 'pnpm-lock.yaml'
yaml
构建时的 base URL
Vue 3 项目部署到 GitHub Pages 时，URL 路径包含仓库名：
// vite.config.ts
export default defineConfig({
base: process.env.VITE_BASE_URL || '/',
})
typescript
# GitHub Actions 中设置环境变量
- name: Build
run: pnpm build
env:
VITE_BASE_URL: /${{ github.event.repository.name }}/
yaml
在线编辑 Workflow
方式一：GitHub 网页编辑
- 进入仓库 → Actions 标签
- 选择对应的 workflow
- 点击文件链接 → Edit this file
- 直接在网页上编辑并提交
方式二：本地编辑
# 拉取最新代码
git pull
# 编辑 workflow 文件
# .github/workflows/deploy.yml
# 提交并推送
git add .github/workflows/deploy.yml
git commit -m "ci: update deploy workflow"
git push
bash
GitHub Pages 设置
- 进入仓库 → Settings → Pages
- Source 选择 Deploy from a branch
- Branch 选择 gh-pages 分支
- 保存后等待部署完成
常见问题
| 问题 | 原因 | 解决方案 |
|---|---|---|
| 页面空白 | base URL 未配置 | 设置 VITE_BASE_URL 为仓库名路径 |
| 404 错误 | gh-pages 分支不存在 | 确认 workflow 已成功运行并创建了 gh-pages 分支 |
| 依赖安装失败 | lock 文件不一致 | 使用 --frozen-lockfile 并确保 lock 文件最新 |
| 权限错误 | GITHUB_TOKEN 权限不足 | 在 workflow 中添加 permissions 配置 |
构建产物路径
项目根目录/
├── dist/ ← 构建输出目录
│ ├── index.html
│ └── assets/
│ ├── index-*.js
│ └── index-*.css
└── .github/
└── workflows/
└── deploy.yml
text
实践要点
- GitHub Actions 的
GITHUB_TOKEN自动提供，无需手动创建 - 部署到 GitHub Pages 需要配置正确的 base URL（
/仓库名/） - 使用
peaceiris/actions-gh-pages简化部署流程 - pnpm 项目需额外配置
pnpm/action-setup安装 pnpm - 线上部署路径与本地开发路径不同，注意 base 配置
↑