Hugo + PaperMod 博客搭建记录(含踩坑)

Fri, 07 Aug 2026 03:30:00 +0800

本博客即本文的产物。记录完整搭建过程和踩过的坑,供以后重建参考。

技术选型

Hugo v0.164.0(extended)— Go 单二进制,极快
PaperMod 主题 — 极简技术风,内置搜索/归档/标签
目标:按日期更新的技术日志流

搭建步骤

1. 安装 Hugo(容器内,免 root)

# 下载官方 release 的 tar.gz 到用户目录(路径按实际环境替换)
curl -L "https://github.com/gohugoio/hugo/releases/download/v0.164.0/hugo_extended_0.164.0_linux-amd64.tar.gz" -o /tmp/hugo.tar.gz
mkdir -p ~/bin && tar -xzf /tmp/hugo.tar.gz -C ~/bin hugo
# 验证
~/bin/hugo version

2. 建站点 + 装主题

cd ~ && ~/bin/hugo new site techlog
git clone --depth 1 https://github.com/adityatelange/hugo-PaperMod ~/techlog/themes/PaperMod

3. 配置 config.toml(中文)

关键配置点:

theme = "PaperMod"
菜单:归档 / 搜索 / 标签
输出:HTML + RSS + JSON(搜索需要)

4. 创建归档/搜索页面

<!-- content/archives.md -->
---
title: "归档"
layout: "archives"
url: "/archives/"
---

<!-- content/search.md -->
---
title: "搜索"
layout: "search"
url: "/search/"
---

5. 构建

hugo --minify # 输出到 public/

踩坑记录

坑 1:hugo.toml vs config.toml 并存

Hugo 0.164 的 hugo new site 默认生成 hugo.toml,如果又写了 config.toml,两个文件并存时 hugo 优先读 hugo.toml(还是默认内容),你的配置全部不生效。

Hugo on TechLog 技术日志

Hugo + PaperMod 博客搭建记录(含踩坑)

技术选型

搭建步骤

1. 安装 Hugo(容器内,免 root)

2. 建站点 + 装主题

3. 配置 config.toml(中文)

4. 创建归档/搜索页面

5. 构建

踩坑记录

坑 1:hugo.toml vs config.toml 并存