博客上线前那个晚上，我 hugo server 一跑，页面出来了，但长得不对——素面朝天，明显是 Hugo 的默认脸，我精心挑选的 PaperMod 主题根本没生效。我翻来覆去检查配置文件，三个小时后才发现：网站根目录下躺着两个配置文件，Hugo 读了我没写内容的那份。那天折腾到半夜一点，第二天早上送孩子上学时眼睛都是花的。

下面是我搭这个博客的全过程，顺利的地方三言两语，踩坑的地方细说——毕竟坑才是这篇文章的价值。

装 Hugo：别用 apt，直接下官方包

Ubuntu 的 apt 仓库里有 Hugo，但版本老。我一开始图省事 apt install hugo，装完 hugo version 一看，版本号比 PaperMod 要求的低了一大截。果断卸载，改去 Hugo 官网下载了 extended 版的 deb 包：

sudo dpkg -i hugo_extended_0.x.x_linux-amd64.deb
hugo version

为什么非要 extended 版？PaperMod 的某些功能（比如处理 SCSS 样式）依赖它。普通版装上也能跑，但迟早会在某个功能上翻车，不如一步到位。这个教训的学费，是我卸载重装那十分钟——外加去官网找对应 deb 包时，对着一堆版本号挑花眼的五分钟。认准 hugo_extended 开头、系统架构 linux-amd64 的那个，别下错成 ARM 版（树莓派才用那个）。

加 PaperMod 主题

PaperMod 是 Hugo 生态里很受欢迎的主题，干净、快、对中文友好。用 git submodule 的方式装，方便以后更新：

cd ~/blog
git init
git submodule add https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod

然后在 hugo.toml 里指定主题：

theme = "PaperMod"

用 submodule 而不是直接下载 zip 包，好未来更新主题。PaperMod 更新挺勤快，隔几个月跑一次就行：

cd ~/blog
git submodule update --remote themes/PaperMod

更新完本地 hugo server 瞄一眼，没跑版再发布。主题大版本更新偶尔会改配置项，更新前扫一眼它的 release 说明，花不了两分钟，能避掉很多"昨天还好好的"的灵异事件。这跟汽车保养看一眼手册一个道理，省小事，避大事。

写中文配置：就是在这里翻的车

这是我的 hugo.toml 核心部分：

baseURL = "https://opusmia.com/"
languageCode = "zh-CN"
defaultContentLanguage = "zh-CN"
title = "我的博客"
theme = "PaperMod"

翻车经过是这样的：我一开始按某篇教程建了 config.toml，又按 PaperMod 官方文档建了 hugo.toml，两个文件都在根目录躺着。Hugo 的读取优先级我没搞明白，结果它读了几乎空的 config.toml，主题配置全没生效。页面能打开，但长得"不对"，我对着文档查了三个小时，最后 ls 一看，两个配置文件并排站着，瞬间明白了。

解决办法：删掉多余的那个，只留 hugo.toml。教训：一个项目只用一种配置文件格式，别看什么教程写什么。我现在回想，那天晚上但凡早点 ls 一下，能省两小时——以及第二天早上的黑眼圈。

配 Nginx：把 public 指对地方

Hugo 生成静态文件很快：

hugo

当前目录下会多出个 public 文件夹，这就是网站的全部。Nginx 要做的，就是把这个目录原样扔给访客。我把整个 ~/blog 放在了 /var/www/blog，Nginx 配置这样写：

server {
    listen 80;
    server_name opusmia.com www.opusmia.com;

    root /var/www/blog/public;
    index index.html;

    location / {
        try_files $uri $uri/ =404;
    }
}

这里我又踩了个小坑：第一次 root 写成了 /var/www/blog，少了后面的 /public，打开网站直接 403。Nginx 的 root 必须指向 public，不是项目根目录。这个错误 low 得让我不好意思，但确实发生了——深夜一点的人，眼睛会选择性失明。

还有一个细节：try_files $uri $uri/ =404 这行别漏。Hugo 生成的是纯静态文件，没有这行，访问 /posts/xxx/ 这类带斜杠的路径时 Nginx 会直接 404。有了它，Nginx 会先试文件、再试目录，静态站点的路由就全通了。

写完配置检查语法再重载：

sudo nginx -t
sudo systemctl reload nginx

收尾：写第一篇文章，发布

hugo new posts/hello.md
hugo

写完 markdown，hugo 一下重新生成，Nginx 自动 serve 新文件。静态站的好处就在这里：没有数据库，没有后台，发布就是生成文件，连重启都不用。

我的发布流程现在固定成三步：在电脑上写好 markdown，用 rsync 同步到服务器的 /var/www/blog，SSH 上去 hugo 生成。全程不到一分钟。有人用 Git 钩子自动部署，更优雅，但我这套"手动三步"用了几个月，稳得很——工具顺手比工具时髦重要。

一句话总结

搭 Hugo 博客真正的拦路虎从来不是技术，是配置文件里多出来的那一个，和 root 后面少写的那一级路径。遇到"页面长得不对"，先 ls 看看目录，再怀疑人生。