Vite项目部署GitHubPages的自动化配置

Vite 项目部署到 GitHub Pages 时，最常见的问题有三个：

• 子路径资源 404。

• 刷新路由 404。

• 构建目录和 Pages 上传目录不一致。

如果是项目站点，例如：

https://username.github.io/repository-name/

那 Vite 的 base 一定要处理好。

基础工作流

name: CI / Deploy

on:
  push:
    branches: ["main"]
  pull_request:
    branches: ["main"]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

pages: write 和 id-token: write 是 GitHub Pages Actions 部署需要的权限。

安装和构建

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup pnpm
        uses: pnpm/action-setup@v4
        with:
          version: latest

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: pnpm

      - name: Install dependencies
        run: pnpm install --frozen-lockfile

      - name: Build
        run: pnpm build
        env:
          VITE_BASE_URL: /${{ github.event.repository.name }}/

这里用仓库名自动生成 VITE_BASE_URL，避免项目复制后忘记改 base。

Vite 配置里可以这样接：

import { defineConfig } from "vite";

export default defineConfig({
  base: process.env.VITE_BASE_URL || "/",
});

只在 main 分支部署

PR 只跑构建检查，不部署：

      - name: Setup Pages
        if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
        uses: actions/configure-pages@v5

      - name: Upload Pages artifact
        if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./dist

部署 Job

  deploy:
    needs: build
    if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v5

SPA 刷新 404

如果是 Vue Router / React Router 的 history 模式，刷新 /docs/xxx 可能 404。最简单的处理方式是在构建产物里复制一份 404.html：

- name: Copy index.html to 404.html
  run: cp dist/index.html dist/404.html

如果项目不需要 Jekyll，建议加 .nojekyll：

- name: Create .nojekyll
  run: touch dist/.nojekyll

完整构建后：

- name: Build project
  run: pnpm build
  env:
    VITE_BASE_URL: /${{ github.event.repository.name }}/

- name: Create .nojekyll
  run: touch dist/.nojekyll

- name: Copy index.html to 404.html
  run: cp dist/index.html dist/404.html

- name: Upload artifact
  uses: actions/upload-pages-artifact@v3
  with:
    path: dist

文档自动同步再部署

如果站点文档来自另一个仓库、npm 包、Release 或接口，可以加一个定时工作流：

on:
  schedule:
    - cron: "0 0 * * *"
  workflow_dispatch:

同步后如果文件变化，就自动提交：

- name: Commit and push synced files
  run: |
    git config user.email "github-actions[bot]@users.noreply.github.com"
    git config user.name "github-actions[bot]"
    git add src/content/docs/ public/downloads/
    if git diff --staged --quiet; then
      echo "No synced changes to commit."
    else
      git commit -m "docs: sync external docs and downloads"
      git push
    fi

然后继续执行构建和 Pages 部署。

常见排查

如果 Pages 部署失败，可以先看 build 和 deploy 是哪一步失败：

• build 失败：通常是依赖、类型检查、base 配置、构建命令问题。

• artifact 上传失败：通常是 dist 目录不存在。

• deploy 失败：可能是 Pages 设置、权限、GitHub Pages 临时问题。

如果 build 成功、artifact 成功，只有 deploy 失败，可以优先尝试重新运行工作流。

总结

Vite + GitHub Pages 的核心配置是：

• base 指向仓库子路径。

• dist/.nojekyll 避免 Jekyll 处理静态资源。

• dist/404.html 处理 history 路由刷新。

• PR 只构建，main 才部署。

• 文档类站点可以加定时同步。

把这几个点固定成模板后，以后任何 Vite 静态项目都可以很快上线。