Hugo 的主题有几百个，PaperMod 是中文圈里被推荐最多的那个。14000 颗星，MIT，一个作者维护了五年。

它属于「装上就不想改」的类型：没有花哨动效，没有一堆配色方案，就是一个干净的阅读界面。第一次打开会觉得太素，用久了会发现该有的都有。

一、它是什么

先说清楚一件事：PaperMod 是主题，不是建站程序。

它得配 Hugo 用。Hugo 是一个用 Go 写的静态站点生成器，下载一个 exe，把 Markdown 编译成 HTML。PaperMod 负责长什么样，Hugo 负责把内容渲染出来。

所以你不能像装 WordPress 那样传个压缩包上去就有后台。这里的流程是：本地写 Markdown → 跑一条命令 → 得到一堆 HTML → 传服务器。

代价是学习成本，好处是服务器上没有任何能崩的东西。

二、三种首页形态

同样一套内容，PaperMod 能给三种首页：

Regular，博客列表。最常规的那种，顶部一段介绍，下面是文章卡片。

Home-Info，跟 Regular 差不多，但顶部那块信息区更突出，适合放自我介绍。

Profile，只剩头像、名字、一句话和一个按钮。整页就这些，点进去才看到文章。这个形态被抄得最多，很多个人主页都是这个样子。

切换只改配置，不用动模板：

params:
  profileMode:
    enabled: true
    imageUrl: "/images/avatar.png"
    buttons:
      - name: 文章
        url: posts/

开了 profileMode 记得把 homeInfoParams 注释掉，两个都开着会打架。

列表页是这样的，一篇一张卡片，有封面就显示封面，没有就纯文字：

文章列表

三、暗色模式不闪

这是 PaperMod 做得最细的一处。

很多站的暗色模式有个毛病：刷新时先白闪一下。原因是 CSS 要等 JS 读完 localStorage 才生效，而浏览器已经开始绘制了。

PaperMod 在 <head> 里塞了一段同步脚本，抢在首屏绘制之前把 data-theme 属性写到 <html> 上。CSS 变量跟着属性走，第一次绘制就是正确颜色。

三种模式：auto 跟随系统、light、dark。用户点过切换按钮之后，选择存 localStorage，系统偏好被忽略。

暗色模式

四、搜索是前端做的

不用装任何插件。首页输出一个 JSON 索引，搜索页用 Fuse.js 在浏览器里查。

要三个地方配合：outputs.home 里加 JSON、建一个 layout: search 的页面、菜单里加链接。漏掉第一个，搜索框会出现但输什么都没结果——因为索引文件 404，控制台报错但不影响页面渲染，很容易以为是主题坏了。

中文搜索能用，但不如英文准。Fuse.js 是按字符做模糊匹配，不做分词，搜「部署」能命中包含这两个字的段落，搜「怎么部署」就不一定。要真正的中文分词得上 Algolia 或 Pagefind。

五、归档和标签

归档页按年月分组，月份名是主题的中文翻译，不用自己写：

标签和分类是两个独立页面，都是标签云那种排法，后面带数字表示文章数。

六、安装

三种方式，我推荐第二种。

一、手动下载。去 GitHub Releases 下 tar.gz，解压到 themes/PaperMod。缺点：升级要重新下一次。

二、直接拷进仓库。把主题文件放进 themes/PaperMod，跟站点一起提交。主题才 500KB，这点体积换来的是「换台机器 clone 下来就能构建」。我用的是这个。

三、git submodule。看起来最优雅，实际最坑：忘了 --recursive 就是空的主题目录，改了主题推不上去，Actions 里还得单独配。踩过两次之后我就放弃了。

Hugo Modules 也行，但要装 Go 环境，为了一个主题不值。

七、主题版本和 Hugo 版本必须对齐

这是这篇最想说的部分。

PaperMod v8.0 发布于 2024 年 11 月。我一开始配的是最新版 Hugo 0.168（2026 年 10 月），hugo 命令直接报错：

ERROR The "gist" shortcode was deprecated in v0.143.0 and removed in v0.156.0.
ERROR executing "partials/templates/opengraph.html":
      partial "partials/templates/_funcs/get-page-images" not found
ERROR can't evaluate field Social in type *page.siteWrapper

三个问题，全是 Hugo 侧的单方面改动：

site.Social 被删了。 Hugo 0.156 移除了 site.Social，统一用 site.Params.social。PaperMod 的 opengraph.html 和 twitter_cards.html 里各有一处旧写法作为「向后兼容」的兜底分支，新 Hugo 执行到那里就崩。

partial 调用不认 partials/ 前缀了。 模板里写的是 partial "partials/templates/_funcs/get-page-images"，新版要求去掉前缀写成 partial "templates/_funcs/get-page-images"。这个改动没在 release notes 里显著提示，只在构建时给个 warning。

gist shortcode 被移除。 0.143 废弃，0.156 删除。如果你的文章里用了它，会直接报错。

改法都是小改：两处 site.Social.xxx 换成不访问（因为已经在用 params.social），三个文件里的 partials/ 前缀删掉。改完就能跑。

但更省事的做法是把 Hugo 降到主题同期的版本。 v8.0 发布时对应的是 Hugo 0.139 左右，那个组合是作者测过的。我包里带的是 0.168 加打补丁的主题，两种路线都写进说明了。

八、搜索结果里全是同一篇

这个 bug 更隐蔽。

hugo server 下搜索「部署」，出来 20 条，全是同一篇文章。看一眼 index.json，70 条记录里每篇文章重复了 10 次——正好是我改过文件的次数。

根因在主题的 layouts/_default/index.json：

{{- $.Scratch.Add "index" slice -}}
{{- range site.RegularPages -}}
  {{- $.Scratch.Add "index" (dict "title" .Title ...) -}}
{{- end -}}

Scratch 挂在 page 对象上。hugo server 热重建时 page 对象被复用，Scratch 里上一次的条目还在，于是每次重建都再 append 一遍。静态构建（hugo）不会，因为进程重开。

修法是把 Scratch 换成局部变量：

{{- $index := slice -}}
{{- range site.RegularPages -}}
  {{- $index = $index | append (dict "title" .Title ...) -}}
{{- end -}}

局部变量每次执行都是新的，不会累积。我在 site/layouts/_default/index.json 里覆盖了主题的实现，包里的版本已经修好。

顺带一提，这个坑只有在改过内容之后才会出现。第一次构建是正常的，所以很容易被当成灵异事件。

九、缺点

先说清楚它能渲染成什么样，再说不足。下面这一页把标题、列表、引用、代码、表格、脚注全摆了一遍：

排版元素

代码高亮、表格、任务列表、脚注都支持。真正的问题在别处：

没有后台。 写文章要开编辑器，改配置要读 YAML。对不写代码的人不友好。

主题更新慢。 v8.0 之后 master 一直在改，但没有新 tag。上面那些兼容问题就是这么攒下来的。

配置项分散且没有对照表。 官方 wiki 有，但是英文，按功能分类而不是按「我想改哪儿」分类。第一次配会花不少时间找。

不支持评论。 要自己接 Giscus 或 Disqus，主题只留了 comments: true 的位置。

中文排版一般。 段落间距、行高都是按英文调的，中文长段落读起来略挤。这个得自己改 CSS。

手机版

十、自己动手的成本

装主题本身十分钟。时间花在这些地方：params 下面几十个开关得一个个试；hasCJKLanguage 不开，字数和阅读时长算得离谱；搜索三处配置缺一不可；版本对齐最容易被跳过——我第一次直接下了最新 Hugo，报了一堆看不懂的错。

十一、我打的这个包

为了跳过「装 Hugo + 配环境 + 修兼容」这三步，包里塞了一份便携 Hugo 0.168 extended，双击 bat 就能看效果。

文章页

包里有一个完整的六篇文章的演示站，覆盖首页、列表、文章、归档、标签、分类、搜索、暗色、手机版。主题本体在 site/themes/PaperMod，六篇文章和封面可以随便删。

路径	内容
`site/`	完整 Hugo 站点，配置 + 6 篇文章 + 主题
`hugo/hugo.exe`	Hugo 0.168.0 extended，单文件免安装
`启动预览.bat`	双击起服务，浏览器自动打开
`预览截图/`	11 张，就是跑起来的这个站
`原始包/`	PaperMod v8.0 官方源码