Hugo 博客更换 Reimu 主题完全记录

2026-08-13

前言

用了一段时间 PaperMod，虽然轻量快速但看久了有点单调。偶然发现了 hugo-theme-reimu 这款博丽灵梦风格的主题，二次元味拉满，特效也很丰富，果断换上。

本文记录更换过程中的配置、踩坑和优化。

主题特色

Reimu 主题功能非常丰富，列举几个我最喜欢的：

🎨 博丽灵梦红白配色，风格统一
🌀 太极加载动画（少女祈祷中…）
✨ 鼠标点击烟花特效
🌙 亮/暗模式切换
📱 响应式布局，移动端适配好
🔍 Algolia 搜索支持
💬 多种评论系统集成
🎵 APlayer / Meting 音乐播放器
📐 KaTeX / MathJax 数学公式
📊 Mermaid 流程图

安装主题

方式一：Git Submodule（推荐）

1
2
cd your-hugo-site
git submodule add https://github.com/D-Sketon/hugo-theme-reimu.git themes/reimu

方式二：直接克隆

1
git clone --depth=1 https://github.com/D-Sketon/hugo-theme-reimu.git themes/reimu

基础配置

在 hugo.yaml 中添加：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
theme: "reimu"
defaultContentLanguage: "zh-cn"

params:
  mainSections: ["post"]
  dateFormat: "2006-01-02"
  author: "你的名字"

  menu:
    - name: home
      url: ""
    - name: archives
      url: "archives"

文章目录

Reimu 主题默认文章在 content/post/ 目录下，确保你的文章都放对位置。

如果之前用的是 posts（复数），需要改配置或者迁移目录：

1
2
# 迁移文章目录
mv content/posts content/post

常见问题

1. section 页面 404 / 没有 layout

Reimu 主题没有默认的 list.html，只有 archives 有专门的 section 模板。所以像 /categories/、/tags/ 这样的分类/标签页是正常的（用 taxonomy 模板），但自定义的 section（比如 /games/）会找不到布局。

解决方案：

做成普通文章页面（post），通过自定义 URL 访问
或者在 layouts/ 下添加自定义 section 模板

2. author 参数报错

error calling safeHTML: unable to cast hmaps.Params of type hmaps.Params to string

这是因为 params.author 写成了对象格式，Reimu 期望是字符串。

1
2
3
4
5
6
7
8
9
# ✅ 正确
params:
  author: "JiangYM"

# ❌ 错误
params:
  author:
    name: "JiangYM"
    avatar: "/avatar.png"

3. 游戏/静态页面放哪里

独立页面或纯静态内容放 static/ 目录，Hugo 会原样复制到输出目录。

static/
└── games/
    ├── pacman/
    └── 2048-official/

访问路径就是 /games/pacman/。

个性化配置

添加自定义页面

1
2
3
4
5
# 友链页
hugo new friend.md

# 关于页
hugo new about.md

然后在导航菜单中添加：

1
2
3
menu:
  - name: friend
    url: "friend"

代码块样式

Reimu 的代码高亮已经很漂亮了，如果想调整，可以在 assets/ 下覆盖主题样式。

性能优化

启用 minify：构建时加 --minify 参数
图片懒加载：Reimu 内置了 lazysizes，自动生效
CDN 加速：主题的第三方库默认走 CDN
Gzip 压缩：Nginx 层开启 gzip

1
hugo --minify

总结

Reimu 是一款颜值很高、功能很全的 Hugo 主题，二次元爱好者必试。配置不算复杂，主要是刚开始要注意几个和其他主题不一样的地方（特别是 author 格式和 section 模板问题）。

换完主题之后，博客的打开体验提升了一大截，每次加载那个太极动画都要看一会儿 🌀

少女祈祷中… ✨