Hugo + Stack 博客部署记录

Hugo 这篇文章记录本次 Hugo + Stack 博客的部署和写作经验，方便后续忘记时快速找回。

部署方案

当前方案：

1
2
3
4
5
6
7
本地 Hugo 博客
    ↓ git push
GitHub 私有仓库
    ↓ Cloudflare Pages 自动构建
Cloudflare Pages 部署
    ↓
自定义域名 example.com

因为 GitHub 私有仓库启用 GitHub Pages 可能需要升级账户，所以改用 Cloudflare Pages。

GitHub Pages Workflow

如果不用 GitHub Pages，可以删除或禁用 .github/workflows/ 下的 Pages 部署文件。

常见相关配置：

1
2
uses: actions/configure-pages@v6
uses: actions/deploy-pages@v4

禁用自动运行可以改成：

1
2
on:
  workflow_dispatch:

Cloudflare Pages 配置

Cloudflare Pages 构建配置：

1
2
3
4
框架预设：Hugo
构建命令：hugo --gc --minify
构建输出目录：public
根目录：留空

如果 Hugo 项目在子目录，例如 blog/，根目录就填 blog。

Hugo 版本

Stack v4 主题需要较新的 Hugo 版本。Cloudflare Pages 中建议添加环境变量：

1
HUGO_VERSION = 0.158.0

如果日志里出现 Hugo 版本过低或主题不兼容，就优先检查这个变量。

config.toml 关键配置

文件位置：

1
config/_default/config.toml

参考配置：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
baseurl = "https://example.com/"
title   = "My Blog"

defaultContentLanguage = "zh"
hasCJKLanguage = true

[pagination]
    pagerSize = 5

[languages]
    [languages.zh]
        locale = "zh-CN"
        label  = "简体中文"
        title  = "My Blog"
        weight = 1

注意：Stack 主题中文 i18n 使用 zh，所以 defaultContentLanguage 保持为 zh。不要随便改成 zh-cn，否则可能导致中文不显示。

新文章放在哪里

普通文章建议放在：

1
2
content/post/my-first-post/index.md
content/post/my-first-post/cover.jpg

每篇文章一个独立文件夹，正文、封面、图片都放一起，后续更好管理。

新文章模板

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
---
title: "文章标题"
description: "一句话摘要"
slug: "my-first-post"
date: 2026-05-15
image: cover.jpg
categories:
    - 技术
tags:
    - Hugo
    - Blog
---

这里开始写正文。

常用字段：

title：文章标题。
description：文章摘要。
slug：文章 URL 的最后一段。
date：发布时间。
image：封面图。
categories：分类。
tags：标签。
comments: false：关闭评论。
math: false：关闭当前文章数学公式渲染。

Markdown 常用写法

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
## 二级标题

这是一段正文。

> 这是一段引用。

| 名称 | 说明 |
| ---- | ---- |
| Hugo | 静态站点生成器 |

```python
print("Hello, Hugo")
```

首页摘要分隔：

1
<!--more-->

数学公式

如果 params.toml 中开启：

1
2
[article]
    math = true

文章里可以写：

1
2
3
4
5
6
7
行内公式：$E = mc^2$

块级公式：

$$
f(x) = x^2
$$

图片

图片建议放在文章目录下：

1
2
3
content/post/my-trip/index.md
content/post/my-trip/cover.jpg
content/post/my-trip/1.jpg

正文插入图片：

1
![图片说明](1.jpg)

连续写多张图片时，Stack 主题会渲染为图片画廊：

1
![图片 1](1.jpg) ![图片 2](2.jpg)

页面和菜单

独立页面放在：

1
2
3
content/page/about/index.md
content/page/archives/index.md
content/page/search/index.md

页面加入左侧菜单：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
---
title: 关于
slug: about
menu:
    main:
        weight: 5
        params:
            icon: user
comments: false
---

weight 控制排序，icon 使用 Tabler Icons 图标名。

Git 回退记录

撤销已经 push 的最近一次提交：

1
2
git revert HEAD
git push

取消还没 push 的最近一次提交：

1
git reset --hard HEAD~1

查看最近提交：

1
git log --oneline -5

取消正在进行中的 revert：

1
git revert --abort

写作建议

分类用大类，例如 技术、生活、阅读。
标签用更细的关键词，例如 Hugo、GitHub、Cloudflare Pages。
文章标题可以用中文，slug 建议用英文或拼音。
封面图和正文图片尽量放在文章同目录。
构建失败时，优先检查 Hugo 版本、主题版本和第一条 ERROR。