GitHub Pages 部署教程

1、准备工作

  • 拥有一个 GitHub 账号
  • 项目代码已经放在 GitHub 仓库中
  • 构建产物输出到一个目录（如 dist）

2、安装部署工具

以 Vite 项目为例。

2.1、使用 gh-pages 部署

推荐使用 gh-pages 工具自动部署：

npm install --save-dev gh-pages

配置：

以 Vite + Vue 项目为例，添加如下配置：

vite.config.ts

// vite.config.ts
export default defineConfig({
  base: '/your-repo-name/', // 注意这里要加上你的 GitHub 仓库名
  ...
})

package.json

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "deploy": "npm run build && gh-pages -d dist"
  }
}

说明：

  • base 是 GitHub Pages 的访问路径
  • gh-pages -d dist 表示把构建后的 dist 目录部署到 gh-pages 分支

一键部署

npm run deploy

执行后会自动：

  1. 执行打包
  2. 将打包后的内容推送到 gh-pages 分支
  3. GitHub 会自动部署这个分支为静态页面

2.2、使用 GitHub Action 部署

配置

以 Vite + Vue 项目为例，添加如下配置：

vite.config.ts

// vite.config.ts
export default defineConfig({
  base: '/your-repo-name/', // 注意这里要加上你的 GitHub 仓库名
  ...
})

创建 GitHub Action 配置

创建 .github/workflows/deploy.yml 文件

name: Deploy to GitHub Pages

on:
  push:
    tags:
      - 'v*'  # 当推送 v 开头的 tag 时触发
  # 允许手动触发部署
  workflow_dispatch:

# 设置 GITHUB_TOKEN 的权限
permissions:
  contents: read
  pages: write
  id-token: write

# 允许一个并发部署
concurrency:
  group: "pages"
  cancel-in-progress: true

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Setup pnpm
        uses: pnpm/action-setup@v2
        with:
          version: 10
          run_install: false

      - name: Get pnpm store directory
        shell: bash
        run: |
          echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV

      - name: Setup pnpm cache
        uses: actions/cache@v3
        with:
          path: ${{ env.STORE_PATH }}
          key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
          restore-keys: |
            ${{ runner.os }}-pnpm-store-

      - name: Install dependencies
        run: pnpm install

      - name: Build project
        run: pnpm build

      - name: Setup Pages
        uses: actions/configure-pages@v4

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

      - name: Deploy
        id: deployment
        uses: actions/deploy-pages@v4

可以配置该 Action 执行的时机，这里配置的时机是：当推送 v 开头的 tag 时触发。

3、Github 配置

在你的仓库页面点击：

Settings → Pages

选择上一步配置的方式

Github 配置

配置完成之后就可以直接访问：

https://your-username.github.io/your-repo-name/

4、自定义域名（可选）

1、在仓库根目录创建一个名为 CNAME 的文件，内容为你的域名，例如：

www.example.com

2、更新Vite配置以适配自定义域名

// vite.config.ts
export default defineConfig({
  base: '/', // 使用自定义域名时，base应该为根路径
  ...
})

3、域名DNS配置

在你的域名服务商处配置DNS记录：

# A记录指向GitHub Pages的IP
@ A 185.199.108.153
@ A 185.199.109.153
@ A 185.199.110.153
@ A 185.199.111.153

# 可选：配置www子域名
www CNAME guizimo.github.io

4、GitHub仓库设置

在你的仓库页面点击：

Settings → Pages

在 Custom domain 字段输入自定义域名，这里以 cova.guizimo.com 为例。

自定义域名

访问 https://cova.guizimo.com 预览效果

预览

5、常见问题

5.1、无法自动开启 HTTPS

等待几小时，或检查 DNS 配置是否正确。

5.2、每次更新并部署后自定义域名失效

仓库根目录创建一个名为 CNAME 的文件，内容为你的域名。这一步是不能省略的。

5.3、刷新页面报错 404

使用 Hash 路由或配置 404.html fallback