基于 GitHub Actions 的零成本自动化部署：把 Vite/Vue3 项目一键发布到 GitHub Pages 的完整实战

1. 实现自动化部署

1.1. 创建 vue 项目

# 1. 安装/确认 Node.js（>=14）
node -v   # 推荐 20.x

# 2. 创建项目（交互式，选 Vue3 + Router 等）
npm init vue@latest github-actions-demo   # 创建vite项目
# 或：vue create github-actions-demo # 创建 vuecli项目
cd github-actions-demo

# 3. 安装依赖 & 本地预览
npm install
npm run dev   # 浏览器打开验证看能否正常运行

1.2. 配置基础路径

把 vite.config.ts / vue.config.js 里的 基础路径 设好，避免白屏。

• Vite：base: '/仓库名/'
• Vue CLI：publicPath: '/仓库名/'

打开 vite.config.js（没有则新建）并写入：

import {fileURLToPath, URL} from "node:url";

import {defineConfig} from "vite";
import vue from "@vitejs/plugin-vue";
import vueDevTools from "vite-plugin-vue-devtools";

// https://vite.dev/config/
export default defineConfig({
  plugins: [vue(), vueDevTools()],
  resolve: {
    alias: {
      "@": fileURLToPath(new URL("./src", import.meta.url)),
    },
  },

  base: "/github-actions-demo/", // 配置基础路径为仓库名
});

注意：一定要与仓库名一致否则会出现找不到资源的问题！！

1.3. 编写 GitHub Actions Workflow

创建文件 .github/workflows/deploy.yml，复制下面内容：

# GitHub Actions 工作流名称（随便取）
name: Deploy Vue 项目到 GitHub Pages

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

# 给 GITHUB_TOKEN 授权（否则后面无法部署 Pages）
permissions:
  contents: read     # 允许读取仓库内容
  pages: write       # 允许写入 GitHub Pages（发布）
  id-token: write    # 允许 OIDC 身份验证（部署时需要）

jobs:
  # 第一个 Job：构建项目
  build:
    runs-on: ubuntu-latest  # 在 GitHub 提供的 Ubuntu 最新虚拟机上运行
    steps:
      # 1. 检出（checkout）代码
      - uses: actions/checkout@v4

      # 2. 安装 Node.js 环境
      - uses: actions/setup-node@v4
        with:
          node-version: 20  # 指定 Node.js 版本为 20
          cache: npm        # 启用 npm 缓存，加快安装速度

      # 3. 安装依赖（等价于 npm install，但 npm ci 更快、更稳定）
      - run: npm ci

      # 4. 构建打包（Vite 会把代码打包到 dist 文件夹）
      - run: npm run build

      # 5. 上传打包好的 dist 文件夹，作为 artifact 供后续部署使用
      - uses: actions/upload-pages-artifact@v3
        with:
          path: ./dist  # 指定要上传的文件夹

  # 第二个 Job：部署到 GitHub Pages
  deploy:
    needs: build  # 必须等 build 任务完成后再执行
    runs-on: ubuntu-latest
    environment:
      name: github-pages  # 指定部署环境名称（固定写法）
      url: ${{ steps.deployment.outputs.page_url }} # 部署完成后生成的访问 URL
    steps:
      # 6. 使用 GitHub 官方的 Pages 部署 Action
      - uses: actions/deploy-pages@v4
        id: deployment  # 给这个步骤起个 ID，方便引用它的输出变量

1.4. 本地 Git 初始化并推送到 GitHub

# 1. 新建仓库（若已 fork/clone 可跳过）
#    GitHub → New repository → 取名 action_vue → 不初始化 README
# 2. 关联远程
git init
git add .
git commit -m "feat: init vue cli project"
git branch -M main
git remote add origin https://github.com/xxxx/xxxx.git # 替换成自己的路径
git push -u origin main

这一阶段是要把所有代码都提交到仓库上，使用 VScode 自带的 git 工具提交也可以。

1.5. 验证 Actions 运行

回到仓库 → Actions 标签页，应出现绿色对勾 ✅。

1.6. 开启 Pages 服务

1. Settings → Pages → Source 选 GitHub Actions。
2. 等 2-3 分钟 ，Pages 会提示部署成功，显示：Your site is live at https://<用户名>.github.io/<仓库名>/，访问这个地址就能看到线上版本。