Hugo Stack 博客搭建记录

Tue, 28 Apr 2026 00:00:00 +0000

主站 - gweb.work.gd 或 lgcr837.github.io

CDN - fast.gweb.work.gd 或 lgcr837-github-io.pages.dev

这个博客是在 2026 年 4 月 19 日完成的。

这个博客由 Hugo 驱动，使用 Stack 主题，部署在 GitHub Pages 上，因为 Hugo 产生的文件是完全静态的。我想分享一下我的过程和遇到的坑，但不要完全照着我的来。

Hugo 可以选择很多主题，最初，我选择 PaperMod 主题，但发现过于简陋，于是选择了 Stack 主题。这是一个卡片式的主题，看起来现代且美观。

为了在 Github Pages 上完成部署，我把老仓库改了个名字，然后重新新建仓库 lgcr837.github.io。

我最初使用了 Github Codespace 来减轻前期调试的负担。

初始化 Hugo 站点

打开这个仓库，创建一个 Github Codespace，打开在线 VSCode 的终端。

错误示范

温馨提示：这是错误示范，是常见误区，不建议执行这一小章节的任何代码内容。

我来演示一下我最初的错误做法

我先安装了 Hugo

1
2
3


$ wget https://github.com/gohugoio/hugo/releases/download/v0.160.1/hugo_0.160.1_linux-amd64.deb
$ sudo dpkg -i hugo_0.160.1_linux-amd64.deb
$ rm hugo_0.160.1_linux-amd64.deb

先确认一下 Hugo 版本

1
2


$ hugo version
hugo v0.160.1-7747abbb316b03c8f353fd3be62d5011fa883ee6 linux/amd64 BuildDate=2026-02-25T16:38:33Z VendorInfo=gohugoio

确认了 Hugo 已经安装之后，准备初始化 Hugo 站点

1
2
3


$ hugo new site . --force
Congratulations! Your new Hugo site is created in /workspaces/lgcr837.github.io.
...

继续

1
2
3
4
5


$ git submodule add https://github.com/CaiJimmy/hugo-theme-stack.git themes/hugo-theme-stack
$ cp -r themes/hugo-theme-stack/demo/* .
$ cp -r themes/hugo-theme-stack/demo/.gitignore . 2>/dev/null
$ hugo --theme hugo-theme-stack --ignoreVendorPaths="**"
ERROR error building site: render: ... TOCSS: failed to transform ... this feature is not available in your current Hugo version, see https://goo.gl/YMrWcn for more information

看样子已经初始化完成了，吗？看提示信息没法正常构建，因为 Stack 主题使用了 SCSS ，但 Hugo 普通版不带有编译 SCSS 功能，会构建错误，需要安装 Extended 版本。

正确示范

安装正确的 Hugo 版本

1
2
3
4
5


wget https://github.com/gohugoio/hugo/releases/download/v0.160.1/hugo_extended_0.160.1_linux-amd64.tar.gz
tar -xzf hugo_extended_0.160.1_linux-amd64.tar.gz
sudo mv hugo /usr/local/bin/hugo
sudo chmod +x /usr/local/bin/hugo
rm hugo_extended_0.160.1_linux-amd64.tar.gz

这样就安装完成了 Extended 版本，看一下版本号有 +extended 就对了

1
2


$ hugo version
hugo v0.160.1-d6bc8165e62b29d7d70ede01ed01d0f88de327e6+extended linux/amd64 BuildDate=2026-04-08T14:02:42Z VendorInfo=gohugoio

添加 Stack 主题，添加为 Git 子模块。

1

git submodule add https://github.com/CaiJimmy/hugo-theme-stack.git themes/hugo-theme-stack

初始化 Hugo 站点

1

hugo new site . --force

之后复制主题的示例配置， Stack 主题的示例文件在 demo 文件夹下，配置在 config/_default/ 下，Stack 使用多文件配置。

1
2


cp -r themes/hugo-theme-stack/demo/* .
cp -r themes/hugo-theme-stack/demo/.gitignore . 2>/dev/null

先尝试启动一下测试服务器来测试效果。(可选)

1
2
3


$ hugo server -D --theme hugo-theme-stack --bind 0.0.0.0 --port 1313 --disableLiveReload
Web Server is available at http://localhost:1313/ (bind address 0.0.0.0)
...

这样测试服务器就在 Codespace 的 1313 端口开放了。

备注：在 VSCode 终端的端口选项卡里可以找到转发的端口

现在服务器大致能正常运行了，但如果每次编辑都打开 Codespace 重新部署不太现实，我们可以使用 Github Actions 进行自动部署。

新建一个 Action -> .github/workflows/hugo.yaml

 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


name: Deploy Hugo site to Pages

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

permissions:
 contents: read
 pages: write
 id-token: write

concurrency:
 group: "pages"
 cancel-in-progress: false

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

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

 - name: Build
 run: hugo --minify --theme hugo-theme-stack

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

 deploy:
 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

这样就会在每一次提交的时候自动部署。现在来到仓库 Setting -> Pages -> Source，选择 Github Actions，这样就会自动部署到 Github Pages 上了，然后稍等片刻就能在 Github Pages 上的网址看到效果，lgcr837.github.io。

注意，如果代码是在 Codespace 编辑的记得提交。

1
2
3


git add .
git commit -m "Gooooooooooooooooooooooooooooooooood Job"
git push

现在整个博客就完成了部署。

添加新文章

要添加新文章，就直接进入这个仓库的content/post/文件夹，然后新建xxxxx.md文件。

Hugo 的文章最前面要添加一个下面这个不然没法识别

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


---
title: "这是标题"
date: 2026-04-26
draft: false
categories: ["这是一个分类"]
tag: [Hugo, 教程]
description: "文章描述"
author: "作者名"
authorLink: "https://example.com"
image: "/img/xxxxx.jpg"
slug: "custom-url"
weight: 1
---

其中这几个为必须因素

参数	说明
title	文章标题
date	写作时间
draft	是否是草稿（草稿不会显示在文章列表中）

其中这几个为可选因素

参数	类型	说明
tag	字符串/数组	文章标签，例如 `tag: [Hugo, 教程]`
categories	字符串/数组	文章分类
description	字符串	文章描述或摘要，显示在文章列表页
author	字符串	作者名称
authorLink	字符串	作者链接
image	字符串	封面图路径，如 /img/xxxxx.jpg
slug	字符串	自定义URL路径
weight	整数	置顶权重，越小越前
comments	布尔值	是否开启评论
toc	布尔值	是否显示文章目录
math	布尔值	是否启用 LaTeX 公式
mermaid	布尔值	是否启用 Mermaid 图表
externalLink	字符串	外部链接，设置后点击文章卡片跳转外部网址
cover.hidden	布尔值	是否在文章内页隐藏封面图

更多配置

更改默认语言

当你第一次进入网站，会发现界面的默认语言还是英语，只能在左下角的设置手动修改。其实可以通过配置文件的方式修改默认语言。我来到 config/_default/hugo.toml 修改并添加添加这样一行把中文设置为默认语言，并加入中日韩文字适配(不然还是容易出问题)。

1
2


defaultContentLanguage = "zh"
hasCJKLanguage = true

然后似乎就成功了。

修改基本信息

来到 config/_default/hugo.toml ，这里能够修改网站的基本信息。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


baseURL = "这里请填写你的网站的链接(如https://lgcr837.github.io)"
languageCode = "zh-cn"
title = "网站名称"

defaultContentLanguage = "zh"

hasCJKLanguage = true

[pagination]
 pagerSize = 5

[permalinks]
 post = "/p/:slug/"
 page = "/:slug/"

[services.disqus]
 shortname = "hugo-theme-stack"

我尝试修改头像，我发现默认的头像是 assets/img/avatar.png ，但我的头像文件是 avatar.webp 文件没法直接替换，所以把自己的头像文件也放进 assets/img/ 文件夹中，然后来到 config/_default/params.toml 替换头像路径。

1
2
3
4
5
6


...
favicon = "img/avatar.webp"
...
[sidebar]
 avatar = "img/avatar.webp"
...

添加评论系统

我决定给博客添加评论系统，考虑到 Giscus 无需服务器即可部署，且 Stack 主题原生支持。

部分版本的 Stack 主题会默认启用 Disqus 评论，但这个国内没法用，我们需要将它去除，否则会和 Giscus 产生冲突。在 config/_default/params.toml 当中找到 [comments.disqus]一整段删了，然后把[comments]修改如下。

1
2
3


[comments]
 enabled = true
 provider = "giscus"

然后开始添加 Giscus，进入仓库设置，Settings -> General -> Features -> 勾选 Discussions，这样确保讨论功能开启，因为 Giscus 的原理就是基于这个。

我们现在给仓库安装 Giscus 应用，打开 GitHub Apps - Giscus 安装 Giscus，注意不要选择全部仓库而是选择你的博客仓库。

然后来到 giscus.app/zh-CN，填写相关内容。

仓库填写用户名/仓库，如 LGCR837/lgcr837.github.io
页面 discussion 映射关系保持默认即可，Discussion 的标题包含页面的 pathname
分类建议选择General因为最适合作为评论，天生为评论所生。强烈不建议使用Announcements，因为这样只有你自己能发表评论，除非你本来的意愿就是这样。
特性按需勾选，但也分享一下我的做法 [ √ ] 启用主帖子上的反应（reaction） [ ] 输出 discussion 的元数据 [ √ ] 将评论框放在评论上方 [ √ ] 懒加载评论
主题按需选择即可

然后下面会自动生成一个代码，把它复制到文本编辑器中我们需要稍作修改。

以这一段为例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


<script src="https://giscus.app/client.js"
 data-repo="LGCR837/lgcr837.github.io"
 data-repo-id="R_kgDOSGj-Ag"
 data-category="General"
 data-category-id="DIC_kwDOSGj-As4C7tiD"
 data-mapping="pathname"
 data-strict="0"
 data-reactions-enabled="1"
 data-emit-metadata="0"
 data-input-position="bottom"
 data-theme="preferred_color_scheme"
 data-lang="zh-CN"
 crossorigin="anonymous"
 async>
</script>

把他转写成 Hugo Stack 的 toml 格式

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


[comments.giscus]
repo = "LGCR837/lgcr837.github.io"
repoId = "R_kgDOSGj-Ag"
category = "General"
categoryId = "DIC_kwDOSGj-As4C7tiD"
mapping = "pathname"
strict = false
reactionsEnabled = true
emitMetadata = false
inputPosition = "bottom"
theme = "preferred_color_scheme"
lang = "zh-CN"
crossorigin = "anonymous"
async = true

转换的过程可以大致遵循下面这个表格 (表格没有列出全部的，一些比较罕见的设置自己搜索)

原本名称	TOML 名称	格式变化
`repo`	`repo`
`repo-id`	`repoId`
`category`	`category`
`category-id`	`categoryId`
`mapping`	`mapping`
`term`	`term`
`strict`	`strict`	`"0"` → `false`，`"1"` → `true`
`reactions-enabled`	`reactionsEnabled`	`"1"` → `true`，`"0"` → `false`
`emit-metadata`	`emitMetadata`	`"0"` → `false`，`"1"` → `true`
`input-position`	`inputPosition`
`theme`	`theme`
`lang`	`lang`
`loading`	`loading`
data-loading	loading	如 “lazy” 等
`crossorigin`	`crossorigin`

然后我们把这一段 toml 添加在 config/_default/params.toml 当中。

温馨提示：请务必填写你的信息，不要照抄本文示例

使用 Cloudflare Pages 进行加速

进入 Cloudflare 的控制台，进入 Workers & Pages 页面，新建一个 Pages，选择 连接 Github 仓库，然后按照指示给仓库安装应用，注意请选定一个仓库而不是默认的全部仓库。然后按照下面这样的方式进行配置。

框架预设 - 在下拉框选择 Hugo
构建命令 - hugo --minify --theme hugo-theme-stack
构建输出目录 - /public 随后添加一个环境变量，用来防止自动使用旧版 Hugo 造成不兼容。
HUGO_VERSION - 0.160.1 然后点击 保存并部署 ，稍等片刻即可使用 lgcr837-github-io.pages.dev 加速访问。之后每一次 Github 仓库的提交都会自动进行部署。

Posts on LGCR837

Hugo Stack 博客搭建记录

初始化 Hugo 站点

错误示范

正确示范

添加新文章

更多配置

更改默认语言

修改基本信息

添加评论系统

使用 Cloudflare Pages 进行加速

CDN 搭建完毕