> For the complete documentation index, see [llms.txt](https://408550179s-organization.gitbook.io/blog/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://408550179s-organization.gitbook.io/blog/vite-xiang-mu-bu-shu-githubpages-de-zi-dong-hua-pei-zhi.md).

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

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

* 子路径资源 404。
* 刷新路由 404。
* 构建目录和 Pages 上传目录不一致。

如果是项目站点，例如：

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

那 Vite 的 base 一定要处理好。

## 基础工作流

```yaml
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 部署需要的权限。

## 安装和构建

```yaml
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 配置里可以这样接：

```ts
import { defineConfig } from "vite";

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

## 只在 main 分支部署

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

```yaml
      - 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

```yaml
  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`：

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

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

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

完整构建后：

```yaml
- 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 或接口，可以加一个定时工作流：

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

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

```yaml
- 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 静态项目都可以很快上线。