个人博客建站系列 #006 | 多仓库自动化部署到github Pages

发表于： 分类于：
字数： 1826 阅读：≈ 4分钟 浏览：

我想要只访问一个域名，访问到主站Hugo-Next主题搭建的站点，然后由于其他主题各有特色和适用场景，比如友链，我希望可以用/webstack子路径访问，技术文档用/docs子路径访问。所以有了下面的设计。

image-20250810150339435

仓库结构规划

本地库私有库公开仓库 B(静态文件)
zuoerblog,存Hugo+Next源码CI构建到zuoer96.github.io
zuoer-vuepressblog-vuepress，存Hugo+Webstack源码CI构建到zuoer96.github.io/docs
zuoer-webstackblog-webstack，存Vuepress源码CI构建到zuoer96.github.io/webstack

生成 SSH Deploy Key

在本地终端运行：

1

ssh-keygen -t ed25519 -C "1745233303@qq.com" -f deploy_key -N ""

你会在执行目录下获得私钥 deploy_key 和公钥 deploy_key.pub

  • 将 私钥内容 (deploy_key) 添加到 私有源码仓库 A 的 Settings → Secrets 中，命名为 ACTIONS_DEPLOY_KEY
  • 将 公钥内容 (deploy_key.pub) 添加到 公开仓库 B 的 Settings → Deploy keys 中，注意选中 Allow write access 以允许写入发布内容

注意不要在项目目录下执行，并将生成的key提交到私有库，否则推送的时候，部署会报错。【绝对禁止将私钥提交到版本库】

创建子项目 vuepress

根据 官网 创建项目

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

# 创建
npm init vuepress zuoer_vuepress

# 推送
git init
git add .
git comment -m "提交"
git branch -M main
git remote add origin git@github.com:zuoer96/blog_vuepress.git
git push -u origin main

# 启动
npm run docs:dev

用 plume 主题

1

npm create vuepress-theme-plume@latest

创建子项目 webstack 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

# 创建
hugo new site zuoer
cd zuoer
git init
git config --global core.autocrlf true # 【可选】
git submodule add https://github.com/shenweiyan/WebStack-Hugo.git themes/WebStack-Hugo 【可选，直接删除信息，然后单仓推送吧，子模块好像有点问题】
move hugo.toml hugo.toml.backup
xcopy themes\WebStack-Hugo\exampleSite\* . /E /H /K

# 启动
hugo server

# 提送
git remote add origin git@github.com:zuoer96/blog_webstack.git
git push -u origin main

编写 GitHub Actions Workflow

Hugo CI 配置

部署Hugo源码到Github项目，并且将构建的静态文件推送到Github Pages库

在私有源码仓库 A 中创建 .github/workflows/deploy.yml 并填写以下内容

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

name: Hugo Build & Deploy

on:
  push:
    branches:
      - main
  workflow_dispatch:

permissions:
  contents: write

jobs:
  build-deploy:
    runs-on: ubuntu-latest
    concurrency:
      group: github-pages-deploy
      cancel-in-progress: false
    
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          submodules: true
          fetch-depth: 0
          lfs: true

      - name: 安装 Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: '0.148.2'
          extended: true

      - name: 构建站点
        run: hugo --minify

      - name: 部署到 zuoer96.github.io/
        uses: JamesIves/github-pages-deploy-action@v4
        with:
          ssh-key: ${{ secrets.ACTIONS_DEPLOY_KEY }}
          repository-name: zuoer96/zuoer96.github.io
          branch: main
          folder: public
          single-commit: true
          clean-exclude: docs,webstack
          commit-message: "Deploy from source"

注意推送目标目录为clean要排除docs,webstack的目录

排除不生效，目录还是被删除了，所以部署万主站后，子站也要部署下触发流水线

Hugo Vuepress CI 配置

部署Hugo Vuepress源码到Github项目，并且将构建的静态文件推送到Github Pages库

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49

name: VuePress Build & Deploy

on:
  push:
    branches:
      - main
  workflow_dispatch:

permissions:
  contents: write

jobs:
  deploy-docs:
    runs-on: ubuntu-latest
    concurrency:
      group: github-pages-deploy
      cancel-in-progress: false

    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

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

      - name: 安装依赖
        run: npm ci

      - name: 构建文档
        env:
          NODE_OPTIONS: --max_old_space_size=8192
        run: npm run docs:build

      - name: 部署到 zuoer96.github.io/docs
        uses: JamesIves/github-pages-deploy-action@v4
        with:
          ssh-key: ${{ secrets.ACTIONS_DEPLOY_KEY }}
          repository-name: zuoer96/zuoer96.github.io
          branch: main
          folder: docs/.vuepress/dist
          commit-message: "Deploy VuePress to /docs"
          target-folder: docs
          single-commit: true
          clean: false # 保留根目录内容

注意推送目标目录为docs，以及不要clean

Hugo Webstack CI 配置

部署Hugo Webstack源码到Github项目，并且将构建的静态文件推送到Github Pages库

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

name: Hugo Webstack Build & Deploy

on:
  push:
    branches:
      - main
  workflow_dispatch:

permissions:
  contents: write

jobs:
  build-deploy:
    runs-on: ubuntu-latest
    concurrency:
      group: github-pages-deploy
      cancel-in-progress: false
    
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          submodules: true
          fetch-depth: 0
          lfs: true

      - name: 安装 Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: '0.148.2'
          extended: true

      - name: 构建站点
        run: hugo --minify

      - name: 部署到 zuoer96.github.io/webstack
        uses: JamesIves/github-pages-deploy-action@v4
        with:
          ssh-key: ${{ secrets.ACTIONS_DEPLOY_KEY }}
          repository-name: zuoer96/zuoer96.github.io
          branch: main
          folder: public
          commit-message: "Deploy Webstack to /webstack"
          target-folder: webstack
          single-commit: true
          clean: false # 保留根目录内容

注意推送目标目录为webstack，以及不要clean

本地 .gitignore 配置（保持清洁）

在私有源码仓库 A 添加 .gitignore，避免误提交生成静态文件：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# ### Hugo忽略配置 ### 
public/
resources/

# ### vuepress忽略配置 ### 
node_modules

/docs/.vuepress/dist
/docs/.vuepress/.cache
/docs/.vuepress/.temp

这样工作区只保留源码，不包含 public/ 输出内容

本地项目设置baseURL

  • hugo 主项目 hugo.yml
1

baseURL = "https://zuoer96.github.io/"
  • vuepress 配置 docs\.vuepress\config.js
1

base: '/docs/', // 设置站点的基础路径
  • hugo webstack 配置 config.toml
1

baseURL = "https://zuoer96.github.io/webstack/"

推送源代码，触发构建部署流程

  1. 在本地提交 Hugo 源码与 workflow 文件：
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

echo "# blog" >> README.md
git init
git add .
git commit -m "Init Hugo source + deploy workflow"
git branch -M main
git remote add origin git@github.com:zuoer96/blog.git
git push origin main

# 同理其他子主题只需要替换远程地址
git remote add origin git@github.com:zuoer96/blog_vuepress.git
git remote add origin git@github.com:zuoer96/blog_webstack.git

2.GitHub Actions 将自动执行 workflow：构建 Hugo 站点，然后把 public/ 内容推送到 公开 Pages 仓库 B。

3.GitHub Pages 使用仓库 B 的 main 分支根目录发布，Build and deployment Source选择Github from a branch，几分钟完成部署，访问 https://zuoer96.github.io 即可查看你的网站。(访问调整到历史域名？无痕浏览器试试，可能是浏览器缓存)

该步骤在github pages action 会触发2个流水线，一个是pages build and deployment，一个是私有库流水线里配置的推送流水线（显示失败）。会有一条失败，但是最终的内容是部署成功的。