Hugo 跨仓库部署 GitHub Actions 完整配置

2026-04-26 约 307 字预计阅读 2 分钟

Hugo 跨仓库部署 GitHub Actions 完整配置

架构概述

部署架构

源码仓库 A：存放 Hugo 博客源码、主题、配置文件
静态仓库 B（如 hex2rgb.github.io）：存放打包后的静态页面

核心流程

SSH 密钥对（本地生成）
    ↓
公钥 → 部署到【静态仓库 B】Deploy Keys
文章底部-如图【1】
私钥 → 加密存入【源码仓库 A】GitHub Secrets
文章底部-如图【2】
    ↓
Actions 执行：安装 Hugo → 打包源码 → 生成 public → 用私钥推送

常见坑点

Job 隔离问题

不同 job 环境完全隔离，执行完毕立即销毁。如果把 build 和 deploy 分为两个 job，打包生成的 public 目录会丢失。

解决：打包和部署必须在同一个 job 里完成。

密钥注入方式

私钥不能直接写在 with 下，必须通过 env 环境变量注入：

env:
  SSH_DEPLOY_KEY: ${{ secrets.SSH_DEPLOY_KEY }}

Hugo 安装方式

不要手动 wget 安装，容易出现环境异常。统一使用官方 Action：peaceiris/actions-hugo@v2

Deploy Key 权限配置

Deploy Key 需要勾选 Allow write access，否则克隆成功后推送时会报权限拒绝错误。

配置步骤

第一步：本地生成 SSH 密钥对

在终端执行：

# 生成安全密钥（无密码）
ssh-keygen -t rsa -b 4096 -C "pages-deploy" -f github_pages_deploy -N ""

生成两个文件：

github_pages_deploy.pub → 公钥（放到静态仓库）
github_pages_deploy → 私钥（放到源码仓库，绝对保密）

查看并复制完整内容：

# 复制公钥
cat github_pages_deploy.pub

# 复制完整私钥（含首尾标记）
cat github_pages_deploy

第二步：配置静态仓库的公钥

进入 hex2rgb.github.io 仓库的 Settings → Deploy keys → Add deploy key

Title：自定义名称（例如 blog 自动推送）
Key：粘贴完整公钥内容
Allow write access：必须勾选
点击 Add key 保存

第三步：配置源码仓库的私钥 Secret

进入源码仓库的 Settings → Secrets and variables → Actions → New repository secret

Name：SSH_DEPLOY_KEY（注意大小写）
Secret：粘贴完整私钥，包括首尾标记

Secrets 是加密存储的，只有这个仓库的 Actions 可以读取，私钥不会暴露。

Workflow 文件

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

name: Deploy Hugo site

on:
  push:
    branches: ["main"]
  workflow_dispatch:

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          submodules: recursive

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: '0.160.1'
          extended: true

      - name: Build Hugo
        run: |
          hugo --minify --baseURL "https://hex2rgb.github.io/"

      - name: Deploy to hex2rgb.github.io
        uses: cpina/github-action-push-to-another-repository@main
        env:
          SSH_DEPLOY_KEY: ${{ secrets.SSH_DEPLOY_KEY }}
        with:
          source-directory: public
          destination-github-username: hex2rgb
          destination-repository-name: hex2rgb.github.io
          target-branch: main
          clean: true
          commit-message: "deploy: update site"

故障排查

错误	原因	解决方案
`SSH_DEPLOY_KEY is empty`	私钥未粘贴完整 / 变量名大小写错误	检查 Secrets 名称（`SSH_DEPLOY_KEY`）和内容完整性
`Could not clone the destination repository`	公钥未配置 / 未勾选读写权限 / 密钥不匹配	确保 Deploy Key 配置正确且勾选了 Allow write access
`ls: public: No such file or directory`	多 job 拆分 / Hugo 构建失败	确保 build 和 deploy 在同一 job，检查 Hugo 版本
克隆成功、推送失败	Deploy Key 缺少写入权限	重新配置 Deploy Key，必须勾选 Allow write access

附件

图 1
图 2