Hugo 博客 CI/CD 实战：GitHub Actions 自动构建与多环境部署

2021-03-21 约 1750 字预计阅读 4 分钟

从最初的手动 hugo && scp 到现在的 Git Push 触发自动部署，这篇文章记录了 Hugo 博客 CI/CD 的演进过程，以及生产级 GitHub Actions 配置的最佳实践。

一、部署方式演进

1.1 青铜：手动部署

1
2
3
4
hugo                     # 构建
tar -czf public.tar.gz public/
scp public.tar.gz server:/tmp/
ssh server "cd /var/www && tar -xzf /tmp/public.tar.gz"

痛点：每次手动操作，容易遗漏步骤，无法追溯历史版本。

1.2 白银：Shell 脚本

1
2
3
#!/bin/bash
hugo && git add . && git commit -m "update" && git push
ssh server "cd ~/blog && git pull && cp -r public/* /var/www/"

痛点：依赖本地环境，不同机器可能构建结果不同。

1.3 黄金：GitHub Actions

1
2
3
4
# Push 触发，云端构建，自动部署
on:
  push:
    branches: [main]

优势：

环境一致性（容器化构建）
版本可追溯
多目标部署
自动化测试

二、GitHub Actions 完整配置

2.1 目录结构

1
2
3
4
.github/
└── workflows/
    ├── deploy.yml        # 主部署流程
    └── preview.yml       # PR 预览

2.2 主部署流程

  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
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
# .github/workflows/deploy.yml
name: Deploy Hugo Blog

on:
  push:
    branches:
      - main
  workflow_dispatch:  # 支持手动触发

# 设置权限（部署到 GitHub Pages 需要）
permissions:
  contents: read
  pages: write
  id-token: write

# 防止并发部署冲突
concurrency:
  group: "pages"
  cancel-in-progress: true

jobs:
  # ========== 构建阶段 ==========
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          submodules: recursive  # 拉取主题子模块
          fetch-depth: 0         # 获取完整历史（用于 lastmod）

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v3
        with:
          hugo-version: '0.139.0'
          extended: true  # 使用 extended 版本（支持 SCSS）

      - name: Cache Hugo modules
        uses: actions/cache@v4
        with:
          path: /tmp/hugo_cache
          key: ${{ runner.os }}-hugo-${{ hashFiles('**/go.sum') }}
          restore-keys: |
            ${{ runner.os }}-hugo-

      - name: Build
        env:
          HUGO_ENVIRONMENT: production
          HUGO_ENV: production
        run: |
          hugo \
            --gc \
            --minify \
            --baseURL "${{ vars.SITE_URL }}"

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./public

  # ========== 部署到 GitHub Pages ==========
  deploy-pages:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

  # ========== 部署到自建服务器 ==========
  deploy-server:
    runs-on: ubuntu-latest
    needs: build
    if: github.ref == 'refs/heads/main'  # 只有 main 分支触发
    steps:
      - name: Download artifact
        uses: actions/download-artifact@v4
        with:
          name: github-pages
          path: ./public

      - name: Extract artifact
        run: |
          cd public
          tar -xf artifact.tar
          rm artifact.tar

      - name: Deploy via rsync
        uses: burnett01/rsync-deployments@7.0.1
        with:
          switches: -avzr --delete
          path: public/
          remote_path: /var/www/blog/
          remote_host: ${{ secrets.DEPLOY_HOST }}
          remote_port: ${{ secrets.DEPLOY_PORT }}
          remote_user: ${{ secrets.DEPLOY_USER }}
          remote_key: ${{ secrets.DEPLOY_KEY }}

2.3 PR 预览流程

 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
# .github/workflows/preview.yml
name: PR Preview

on:
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  preview:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          submodules: recursive

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

      - name: Build (Draft mode)
        run: |
          hugo --buildDrafts --baseURL "/"

      - name: Deploy Preview
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public
          destination_dir: pr-${{ github.event.number }}

      - name: Comment PR
        uses: actions/github-script@v7
        with:
          script: |
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: '预览地址: https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/pr-${{ github.event.number }}/'
            })

三、Secrets 配置

在 GitHub 仓库设置中添加：

Secret 名称	说明	示例
`DEPLOY_HOST`	服务器 IP	`1.2.3.4`
`DEPLOY_PORT`	SSH 端口	`22`
`DEPLOY_USER`	SSH 用户	`deploy`
`DEPLOY_KEY`	SSH 私钥	`-----BEGIN...`

生成部署密钥

1
2
3
4
5
6
7
8
# 本地生成
ssh-keygen -t ed25519 -C "github-actions-deploy" -f deploy_key

# 公钥添加到服务器
cat deploy_key.pub >> ~/.ssh/authorized_keys

# 私钥添加到 GitHub Secrets
cat deploy_key  # 复制内容到 DEPLOY_KEY

四、高级配置

4.1 定时重建（更新 lastmod）

1
2
3
4
5
on:
  schedule:
    - cron: '0 2 * * *'  # 每天凌晨 2 点
  push:
    branches: [main]

4.2 多环境部署

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
jobs:
  build:
    # ...构建步骤...

  deploy-staging:
    needs: build
    if: github.ref == 'refs/heads/develop'
    environment: staging
    # 部署到测试环境

  deploy-production:
    needs: build
    if: github.ref == 'refs/heads/main'
    environment: production
    # 部署到生产环境

4.3 构建缓存优化

1
2
3
4
5
6
7
- name: Cache Hugo modules
  uses: actions/cache@v4
  with:
    path: |
      /tmp/hugo_cache
      node_modules
    key: ${{ runner.os }}-hugo-${{ hashFiles('**/go.sum', '**/package-lock.json') }}

4.4 Dockerfile 构建（更可控）

1
2
3
4
5
6
7
# Dockerfile
FROM hugomods/hugo:exts-0.139.0

WORKDIR /src
COPY . .

RUN hugo --gc --minify

1
2
3
4
5
# GitHub Actions
- name: Build with Docker
  run: |
    docker build -t blog-builder .
    docker run --rm -v $PWD/public:/src/public blog-builder

五、监控与报警

5.1 部署状态徽章

1
![Deploy Status](https://github.com/username/blog/actions/workflows/deploy.yml/badge.svg)

5.2 部署失败通知

1
2
3
4
5
6
7
8
- name: Notify on failure
  if: failure()
  uses: 8398a7/action-slack@v3
  with:
    status: ${{ job.status }}
    fields: repo,message,commit,author
  env:
    SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK }}

六、常见问题

6.1 主题子模块未拉取

1
2
3
- uses: actions/checkout@v4
  with:
    submodules: recursive  # 关键配置

6.2 Hugo 版本不一致

1
2
3
4
# 固定版本，避免意外
- uses: peaceiris/actions-hugo@v3
  with:
    hugo-version: '0.139.0'  # 明确版本号

6.3 构建内存不足

1
2
3
4
5
6
jobs:
  build:
    runs-on: ubuntu-latest
    env:
      HUGO_CACHEDIR: /tmp/hugo_cache
      HUGO_NUMWORKERMULTIPLIER: 1  # 减少并发

七、完整工作流

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
┌─────────────┐     ┌──────────────┐     ┌─────────────────┐
│  Git Push   │────▶│ GitHub       │────▶│ Build Hugo      │
│  (main)     │     │ Actions      │     │ (Container)     │
└─────────────┘     └──────────────┘     └────────┬────────┘
                                                  │
                         ┌────────────────────────┼────────────────────────┐
                         ▼                        ▼                        ▼
                  ┌─────────────┐         ┌─────────────┐         ┌─────────────┐
                  │ GitHub Pages│         │ 自建服务器   │         │ CDN 刷新    │
                  │ (备份)      │         │ (主站)      │         │ (可选)      │
                  └─────────────┘         └─────────────┘         └─────────────┘

八、总结

演进阶段	部署时间	可追溯性	环境一致性
手动	5 分钟	无	差
Shell 脚本	1 分钟	无	一般
GitHub Actions	2 分钟	完整	一致

核心收获：

Git 即部署：Push 即触发，无需额外操作
环境隔离：容器化构建，避免"我机器上能跑"
多目标部署：同时发布到 GitHub Pages 和自建服务器
可观测性：每次部署有记录，失败有通知