Hugo 博客自动化部署：从 GitHub Actions 到 VPS 的保姆级指南

手动部署博客？这简直是石器时代的行为。既然我们已经把代码托管在 GitHub，那么最优雅的方案就是构建一套 CI/CD 流水线：只要 git push，代码自动构建并同步到 VPS。

今天分享一套经过验证的 Hugo -> GitHub Actions -> VPS 自动化方案。

核心链路

整个流程分为三个关键环节：VPS 密钥配置 -> GitHub Secrets 加密 -> Workflow 编排。

第一步：在 VPS 上配置 SSH 免密登录

GitHub Actions 需要一个「通行证」才能在不输入密码的情况下把文件传到你的服务器。

1. 生成 SSH 密钥对（如果已有可跳过）：

   1	ssh-keygen -t ed25519 -C "github-actions-hugo"

   注意：一路回车，不要设置 passphrase。

2. 将公钥加入信任列表：

   1 2 3

   cat ~/.ssh/id_ed25519.pub >> ~/.ssh/authorized_keys chmod 600 ~/.ssh/authorized_keys chmod 700 ~/.ssh

3. 导出私钥（这是后面要填入 GitHub 的关键）：

   1	cat ~/.ssh/id_ed25519

   复制包含 -----BEGIN OPENSSH PRIVATE KEY----- 在内的全部内容。

第二步：在 GitHub 中配置 Secrets

绝对不要把服务器 IP 和私钥明文写在 .yml 文件里，那是给黑客递钥匙。

进入仓库 -> Settings -> Secrets and variables -> Actions，点击 New repository secret 添加以下三个变量：

第三步：编写 Workflow 配置文件

在项目根目录下创建 .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

name: Deploy Hugo Blog to VPS

on:
  push:
    branches:
      - main  # 触发分支，如果是 master 请相应修改

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      # 1. 检出代码 (处理子模块是关键)
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          submodules: recursive 
          fetch-depth: 0

      # 2. 安装 Hugo 环境 (开启 extended 版本支持 SCSS)
      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v3
        with:
          hugo-version: 'latest'
          extended: true 

      # 3. 构建静态文件
      - name: Build Blog
        run: hugo --minify

      # 4. 通过 SSH 部署到 VPS
      - name: Deploy to VPS
        uses: easingthemes/ssh-deploy@main
        env:
          SSH_PRIVATE_KEY: ${{ secrets.VPS_SSH_KEY }}
          ARGS: "-avzr --delete"
          SOURCE: "public/"
          REMOTE_HOST: ${{ secrets.VPS_HOST }}
          REMOTE_USER: ${{ secrets.VPS_USER }}
          REMOTE_PORT: "22" # 根据你的 SSH 端口修改
          TARGET: "/var/www/hugoblg"

⚠️ Bosh 的避坑指南 (Critical Tips)

1. env 还是 with？
   很多教程会把 SSH_PRIVATE_KEY 写在 with: 下面，但在 easingthemes/ssh-deploy 插件中，这些参数必须写在 env: 块中，否则会直接报 SSH_PRIVATE_KEY is mandatory。

2. 目录权限与存在性：
   GitHub Actions 不会自动帮你创建远程目录。请确保 VPS 上 /var/www/hugoblg 已经存在，且 VPS_USER 拥有写入权限。

   1	mkdir -p /var/www/hugoblg

3. 主题子模块 (Submodules)：
   如果你的 Hugo 主题是通过 git submodule add 引入的，checkout 步骤中的 submodules: recursive 必须开启，否则构建出的页面将没有样式。

第四步：验证与生效

本地推送即可触发：

1
2
3

git add .
git commit -m "chore: setup github actions deploy"
git push origin main

打开 GitHub 仓库的 Actions 标签页，看着那个绿色的对勾出现，你就知道可以关掉电脑去喝咖啡了。 ☕️

本文由 BOSH 的博客助手 HerMes 整理 ⚡️