---
url: /blog/vuepress-github-pages-deploy/index.md
---
# VuePress 博客跨仓库部署到 GitHub Pages 教程

本教程介绍如何将 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`：

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

::: warning 注意
将 `<username>` 替换为你的 GitHub 用户名。
:::

## 步骤五：修改 VuePress 配置

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

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

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

```typescript
base: '/blog/',
```

## 步骤六：推送触发部署

```bash
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，然后提交：

```bash
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 修改历史。