chen的文档&blog

外观

VuePress 博客跨仓库部署到 GitHub Pages 教程

复制页面

约 975 字大约 3 分钟

程序型知识网站

2026-03-18

本教程介绍如何将 VuePress 源码仓库的构建产物自动部署到另一个 GitHub Pages 仓库。

适用场景

  • 源码仓库和部署仓库分离（保持源码私有，部署产物公开）
  • 使用 username.github.io 作为博客域名
  • 自动化构建和部署流程

架构说明

┌─────────────────────────┐      ┌─────────────────────────┐
│  源码仓库               │      │  部署仓库               │
│  (如: my-docs)          │      │  (username.github.io)   │
│                         │      │                         │
│  - VuePress 源码        │ ───▶ │  - 静态 HTML/CSS/JS     │
│  - Markdown 文档        │      │  - 公网访问             │
│  - GitHub Actions       │      │                         │
└─────────────────────────┘      └─────────────────────────┘
        GitHub Actions 自动构建并推送

步骤一：创建部署仓库

  1. 访问 https://github.com/new
  2. Repository name 填写：<username>.github.io（如 chen-re1.github.io）
  3. 选择 Public 或 Private（都可以，Pages 页面本身是公开的）
  4. 不要勾选任何初始化选项（README、.gitignore 等）
  5. 点击 Create repository

创建后是一个空仓库，不需要添加任何文件。

步骤二：创建 Personal Access Token

由于要从源码仓库部署到另一个仓库，需要 Token 权限：

  1. 访问 https://github.com/settings/tokens/new
  2. 配置：
    • Note: deploy-pages（或任意名称）
    • Expiration: 建议选择 90 天或更长
    • 权限勾选:
      • ✅ repo（完整仓库权限）
      • ✅ workflow（允许操作 workflow 文件）
  3. 点击 Generate token
  4. 立即复制 Token（只显示一次）

步骤三：配置源码仓库 Secret

  1. 打开源码仓库的 Settings → Secrets and variables → Actions
  2. 点击 New repository secret
  3. 配置：
    • Name: PAGES_DEPLOY_TOKEN
    • Value: 粘贴刚才复制的 Token
  4. 点击 Add secret

步骤四：创建/修改 GitHub Actions Workflow

在源码仓库创建 .github/workflows/deploy-docs.yml：

name: 部署文档

on:
  push:
    branches:
      - main

permissions:
  contents: read

jobs:
  deploy-gh-pages:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: 安装 pnpm
        uses: pnpm/action-setup@v4
        with:
          version: 9

      - name: 设置 Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: pnpm

      - name: 安装依赖
        run: pnpm install

      - name: 构建文档
        env:
          NODE_OPTIONS: --max_old_space_size=8192
        run: |-
          pnpm docs:build
          echo "" > docs/.vuepress/dist/.nojekyll

      - name: 部署到 GitHub Pages
        uses: JamesIves/github-pages-deploy-action@v4
        with:
          token: ${{ secrets.PAGES_DEPLOY_TOKEN }}
          repository-name: <username>/<username>.github.io
          branch: main
          folder: docs/.vuepress/dist
          single-commit: true

注意

将 <username> 替换为你的 GitHub 用户名。

步骤五：修改 VuePress 配置

确保 docs/.vuepress/config.ts 中的 base 配置正确：

export default defineUserConfig({
  base: '/',  // 使用 username.github.io 根域名时为 '/'
  // ...
})

如果是子路径部署（如 username.github.io/blog/），则改为：

base: '/blog/',

步骤六：推送触发部署

git add .
git commit -m "setup GitHub Pages deployment"
git push

推送后，去源码仓库的 Actions 页面查看构建进度。

常见问题

1. pnpm-lock.yaml 不同步

错误信息：

ERR_PNPM_OUTDATED_LOCKFILE  Cannot install with "frozen-lockfile"

解决方案：本地运行 pnpm install 更新 lockfile，然后提交：

pnpm install
git add pnpm-lock.yaml
git commit -m "update pnpm-lock.yaml"
git push

2. 图片文件找不到

错误信息：

Could not load .../xxx.png: ENOENT: no such file or directory

原因：Markdown 中引用的图片路径与实际文件名不匹配。

解决方案：统一修正 Markdown 中的图片引用路径。

3. Token 权限不足

错误信息：

refusing to allow a Personal Access Token to create or update workflow

解决方案：重新创建 Token，确保勾选 workflow 权限。

4. 部署仓库触发了额外的 Workflow

如果部署仓库（username.github.io）也有 workflow 文件，可能导致冲突。

解决方案：

  • 在部署仓库的 Settings → Actions → General 中选择 Disable actions
  • 或删除部署仓库中的 .github/workflows/ 目录

验证部署成功

  1. 构建完成后，访问 https://<username>.github.io/
  2. 如果页面未更新，等待 1-2 分钟后刷新（CDN 缓存）
  3. 检查部署仓库是否有构建产物

总结

步骤操作
1创建 username.github.io 空仓库
2创建 PAT（勾选 repo + workflow）
3在源码仓库配置 PAGES_DEPLOY_TOKEN Secret
4创建/修改 workflow 文件
5确保 base 配置正确
6推送代码触发自动部署

💡 提示：部署成功后，建议在源码仓库的 config.ts 中更新 changelog.repoUrl 指向正确的源码仓库地址，以便在博客中显示 Git 修改历史。