从零搭建 Hugo 博客并部署到 GitHub Pages

背景#

之前博客用 Next.js + Express + PostgreSQL 搭的，一套下来几十个依赖，光登录页的 redirect loop 就修了好几次。写个博客而已，搞这么重干嘛？

决定迁移到 Hugo —— 纯静态，Markdown 写文章，git push 自动部署，零运行时依赖。

1. 创建 GitHub 仓库#

新建一个公开仓库 blog-hugo。

2. 初始化 Hugo 项目#

本地安装 Hugo（extended 版本，支持 Sass）：

1
# Linux
2
wget https://github.com/gohugoio/hugo/releases/download/v0.147.0/hugo_extended_0.147.0_linux-amd64.tar.gz
3
tar xz && sudo mv hugo /usr/local/bin/
4

5
# macOS
6
brew install hugo

初始化站点：

1
hugo new site blog-hugo
2
cd blog-hugo
3
git init
4
git remote add origin https://github.com/你的用户名/blog-hugo.git

3. 选择主题#

用了 PaperMod —— 极简风格，自带深色模式、搜索、标签、分类，社区最大。

1
git submodule add https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod

配置 hugo.toml：

1
baseURL = 'https://你的用户名.github.io/blog-hugo/'
2
languageCode = 'zh-CN'
3
title = "My Blog"
4
theme = 'PaperMod'
5

6
[params]
7
  author = '你的名字'
8
  description = 'Personal blog'
9
  defaultTheme = 'auto'
10
  ShowReadingTime = true
11
  ShowPostNavLinks = true
12
  ShowBreadCrumbs = true
13
  ShowCodeCopyButtons = true
14

15
  [params.homeInfoParams]
16
    Title = "Hi there 👋"
17
    Content = "Welcome to my blog"
18

19
[[menu.main]]
20
  identifier = 'home'
21
  name = 'Home'
22
  url = '/'
23
  weight = 10
24
[[menu.main]]
25
  identifier = 'posts'
26
  name = 'Posts'
27
  url = '/posts/'
28
  weight = 20
29
[[menu.main]]
30
  identifier = 'categories'
31
  name = 'Categories'
32
  url = '/categories/'
33
  weight = 30
34

35
[outputs]
36
  home = ['HTML', 'RSS', 'JSON']

4. 迁移旧文章#

之前文章存在 PostgreSQL 里，用 Node.js 连数据库导出成 Markdown 文件。

每篇文章对应一个 .md 文件，放在 content/posts/ 目录下：

1
---
2
title: "文章标题"
3
date: 2026-05-01T00:00:00+08:00
4
draft: false
5
categories: ["分类名"]
6
tags: ["标签1", "标签2"]
7
description: "文章摘要"
8
---
9

10
正文内容...

5. 配置 GitHub Actions 自动部署#

创建 .github/workflows/deploy.yml：

1
name: Deploy Hugo Blog to GitHub Pages
2

3
on:
4
  push:
5
    branches: [main]
6
  workflow_dispatch:
7

8
permissions:
9
  contents: write
10

11
jobs:
12
  deploy:
13
    runs-on: ubuntu-latest
14
    steps:
15
      - name: Checkout
16
        uses: actions/checkout@v4
17
        with:
18
          submodules: recursive
19
          fetch-depth: 0
20

21
      - name: Setup Hugo
22
        uses: peaceiris/actions-hugo@v3
23
        with:
24
          hugo-version: 'latest'
25
          extended: true
26

27
      - name: Build
28
        run: hugo --minify --baseURL "https://你的用户名.github.io/blog-hugo/"
29

30
      - name: Deploy to docs folder
31
        run: |
32
          cp -r public /tmp/public
33
          git checkout main
34
          rm -rf docs
35
          mkdir -p docs
36
          cp -r /tmp/public/* docs/
37
          git config user.name "github-actions[bot]"
38
          git config user.email "github-actions[bot]@users.noreply.github.com"
39
          git add docs/
40
          git commit -m "deploy: update site" || echo "No changes"
41
          git push

6. 启用 GitHub Pages#

在仓库 Settings → Pages 中，设置：

Source: Deploy from a branch
Branch: main / docs 文件夹

每次 push 到 main 分支，Actions 自动构建 Hugo 并把产物推到 docs/ 目录，GitHub Pages 自动部署。

7. 日常写文章#

在本机 clone 仓库后：

1
# 写新文章
2
hugo new content content/posts/my-new-post.md
3

4
# 编辑文章
5
vim content/posts/my-new-post.md
6

7
# 本地预览
8
hugo server --buildDrafts
9

10
# 发布：一条命令搞定
11
git add . && git commit -m "new post: xxx" && git push

也可以设置 git alias 更省事：

1
git config alias.publish '!git add . && git commit -m "update posts" && git push'

之后写完文章只需要 git publish 一条命令。

遇到的坑#

坑 1：TOML 字符串转义#

1
# ❌ 错误：单引号内反斜杠转义会报错
2
title = 'ddd\'s Blog'
3

4
# ✅ 正确：用双引号
5
title = "ddd's Blog"

坑 2：Hugo 版本不兼容#

PaperMod 最新版要求 Hugo 0.146+。如果遇到 Min 0.146.0 错误，升级 Hugo 即可。

坑 3：Pages 构建模式#

GitHub Pages 有 legacy 和 workflow 两种构建模式：

legacy：GitHub 自己跑 Jekyll 构建。纯静态 HTML 需要加 .nojekyll 文件跳过 Jekyll
workflow：由 Actions 构建。但 Pages 自己也会触发一次构建，可能冲突

最终方案：Actions 把构建产物推到 main 分支的 docs/ 目录，Pages 用 legacy 模式读 main/docs。最稳。

总结#

项目	之前	现在
前端	Next.js + React + Tailwind	Hugo + PaperMod
后端	Express + PostgreSQL	无（纯静态）
认证	express-session + bcrypt	无
部署	Docker 容器	GitHub Pages
写文章	登录后台 → API 存数据库	本地写 .md → git push
自动部署	无	GitHub Actions

整个博客现在只需要一个 git 仓库，写完文章 push 就上线，再也不用管服务器、数据库、Session 这些东西了。

背景#