静态博客 on 寻 Mi 处

同一个 Hugo 站点，Nginx 配好之后快了一倍

Wed, 11 Jun 2025 21:20:00 +0800

我一开始对 Nginx 托管静态站的理解是，把 root 指过去，try_files 写上，就完事了。

确实能跑。但用 Lighthouse 一测，分数不高。用 curl -w 看各阶段耗时，发现时间都花在传输上，服务器处理只占几毫秒。

也就是说，瓶颈不在 Nginx 的逻辑，在它吐数据的方式。

这篇文章记录一下我把这些都调过一遍之后的结果，首屏从一点六秒降到八百毫秒。

先量一下基线

curl -o /dev/null -s -w "DNS: %{time_namelookup}s\nTCP: %{time_connect}s\nTLS: %{time_appconnect}s\nTTFB: %{time_starttransfer}s\nTotal: %{time_total}s\nSize: %{size_download} bytes\n" https://blog.mibase.top/

这个命令把各个阶段拆开。TTFB 是首字节时间，Total 是总时间。两者的差就是传输时间。

我改之前，TTFB 是 0.18 秒，Total 是 1.2 秒。传输花了一秒多，说明 html 本身太大。

看一下首页的大小：

`1`	`curl -s -o /dev/null -w "%{size_download}\n" https://blog.mibase.top/`

一百二十 KB。对于纯文本的 html 来说，太大了。Stack 主题的首页会列出十几篇文章，每篇带摘要，加上内联的 css，确实容易膨胀。

先把 gzip 打开

gzip on;
gzip_vary on;
gzip_comp_level 6;
gzip_min_length 1024;
gzip_proxied any;
gzip_types
    text/plain
    text/css
    text/xml
    text/javascript
    application/javascript
    application/json
    application/xml
    application/rss+xml
    image/svg+xml;

gzip_comp_level 6 是个折中。1 最快但压缩率低，9 最慢但只多压几个百分点。6 是常用的平衡点，压缩一百二十 KB 的 html 大概花 3 毫秒，压到三十 KB。

gzip_min_length 1024 是小于一 KB 的不压。因为压缩本身有开销，小文件压了反而更大。

gzip_vary on 会在响应里加 Vary: Accept-Encoding，告诉缓存层不同编码的响应要分开存。不加这个，中间有缓存的话可能把 gzip 的内容发给不支持 gzip 的客户端。

gzip_proxied any 是让经过代理的请求也压缩。默认只对没有 Via 头的请求压。用了 Cloudflare 之后，请求都带 Via，不加这个就不压了。

gzip_types 里默认不包含 text/html，因为 Nginx 认为 html 一定要压，它是内置的。但别的类型要显式列出来。

brotli 比 gzip 更好

如果 Nginx 编译的时候带了 brotli 模块，可以再上一层。

Debian 和 Ubuntu 的官方包默认不带，得用第三方源：

1
2

sudo apt install -y libbrotli1
# 用 ondrej 的 nginx 源，或者自己编译

装完之后：

brotli on;
brotli_comp_level 6;
brotli_min_length 1024;
brotli_types
    text/plain
    text/css
    text/javascript
    application/javascript
    application/json
    application/xml
    image/svg+xml;

brotli 对文本的压缩率比 gzip 高百分之十五到二十。同样一百二十 KB 的 html，gzip 压到三十 KB，brotli 能压到二十五 KB。

但 brotli 压缩更慢，级别 11 的时候能慢十倍。级别 6 是个合理的点。

还有个细节，brotli 需要 https 才能被浏览器支持。http 下浏览器不接受 br 编码。

缓存头怎么设

静态博客的资源分成两类，一类是带指纹的，一类是不带的。

Hugo 处理过的 css、js 带指纹，比如 main.a1b2c3d4.css。这类可以设一年：

location ~* \.(css|js|woff2?|ttf|eot)$ {
    expires 1y;
    add_header Cache-Control "public, max-age=31536000, immutable";
    access_log off;
}

图片我用的是 Page Bundle 里的原图，文件名不带指纹。这类设短一点，一周：

location ~* \.(jpg|jpeg|png|gif|webp|avif|svg|ico)$ {
    expires 7d;
    add_header Cache-Control "public, max-age=604800";
    access_log off;
}

html 最短：

location ~* \.html$ {
    expires 10m;
    add_header Cache-Control "public, max-age=600, must-revalidate";
}

must-revalidate 让浏览器在缓存过期后必须回源确认，不能拿旧的凑合。

access_log off 是给静态资源的。这些请求量最大，写日志的开销不小，而且它们的日志没什么分析价值。

http2 和 http3

http2 已经是很成熟的东西了，Nginx 从 1.9.5 开始支持。

server {
    listen 443 ssl;
    http2 on;
    ...
}

注意 Nginx 1.25.1 之后语法变了。以前是 listen 443 ssl http2;，现在是单独一行 http2 on;。用老语法会报一个 deprecation 警告。

http2 的好处是多路复用。同一个连接上可以并发多个请求，不用像 http1.1 那样开六个连接。对于首页要加载几十个资源的场景，提升很明显。

http3 基于 QUIC，Nginx 从 1.25 开始有实验性支持，需要单独编译。我试过一次，配置有点麻烦，而且国内很多网络对 UDP 443 不友好。暂时没用。

try_files 的写法

1
2
3

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

这个写法支持无扩展名的 URL。比如 /p/hello-world/ 会先找目录，找不到再找 /p/hello-world.html。

Hugo 的默认输出是目录加 index.html，所以 $uri/ 那一步就能命中。但如果你改过 uglyURLs，就得靠 $uri.html。

=404 是最后兜底，找不到就返回 404。如果不写这个，Nginx 会返回一个内部的 404 页面，有时候行为不一致。

还有一个优化，把 index 指令写明确：

`1`	`index index.html;`

默认就是 index.html，但写出来能省一次查找。

文件描述符

这个在另一篇里详细说过，这里提一句。静态站请求量大，每个请求都要打开文件，fd 不够会报 Too many open files。

worker_rlimit_nofile 65535;

events {
    worker_connections 8192;
}

worker_rlimit_nofile 是 nginx 自己能打开的文件数上限，要配合 systemd 的 LimitNOFILE 一起调。

sendfile 和 tcp 参数

1
2
3

sendfile on;
tcp_nopush on;
tcp_nodelay on;

sendfile 让 Nginx 用内核的零拷贝直接把文件送到 socket，不用先读到用户态再写出去。静态文件服务必开。

tcp_nopush 是等数据攒够一个包再发，减少小包数量。它和 sendfile 配合使用效果最好。

tcp_nodelay 是不等待，立刻发。它和 tcp_nopush 看起来矛盾，实际上 Nginx 会根据情况自动选择。对于 keepalive 的连接用 nopush，对于要立刻响应的用 nodelay。

keepalive 的调整

1
2

keepalive_timeout 30s;
keepalive_requests 1000;

默认 keepalive_timeout 是 75 秒，太长了，会占着连接不放。30 秒对静态站够用。

keepalive_requests 是单个连接最多处理多少请求。默认 1000，对于首页要加载几十个资源的场景，一次连接就够了。

一个容易忽略的点：open_file_cache

这个功能会缓存打开的文件句柄，减少 open() 系统调用。

open_file_cache max=10000 inactive=30s;
open_file_cache_valid 60s;
open_file_cache_min_uses 2;
open_file_cache_errors on;

max=10000 是最多缓存一万个文件描述符。inactive=30s 是三十秒没被访问就释放。

open_file_cache_min_uses 2 是至少被访问两次才缓存。只访问一次的文件，缓存了也是浪费。

这个对静态站的效果挺明显，尤其是文章页多的时候。我用 strace 看过，开了之后 openat 调用少了很多。

不过要小心，如果你的文件经常变（比如部署的时候覆盖），缓存可能导致短时间读到旧文件。open_file_cache_valid 60s 是六十秒校验一次，影响不大。

部署时的原子替换

Hugo 构建的时候会先写到一个临时目录，然后整体替换 public。但如果在替换的过程中有请求进来，可能读到一半新一半旧的内容。

我的做法是构建到新目录，然后用符号链接切换：

1
2

hugo --minify --gc -d /srv/www/blog/releases/$(date +%s)
ln -sfn /srv/www/blog/releases/$(date +%s) /srv/www/blog/current

Nginx 的 root 指向 /srv/www/blog/current。

符号链接的切换是原子的，Nginx 打开文件的时候会跟随链接，所以不会有中间状态。

这个做法还有个好处，回滚就是把链接指回上一个目录，一秒搞定。

改完之后的效果

`1`	`curl -o /dev/null -s -w "TTFB: %{time_starttransfer}s\nTotal: %{time_total}s\nSize: %{size_download}\n" https://blog.mibase.top/`

TTFB 0.09 秒，Total 0.28 秒，Size 28 KB。

从一点二秒到零点二八秒。Lighthouse 移动端从 62 分到 96 分。

哪些改动最有用

如果只能做三件事，我会选这三件。

开 gzip，或者 brotli。这个改动最小，收益最大，html 从一百二十 KB 降到三十 KB。

给静态资源设长缓存。第二次访问的时候，浏览器直接用本地的，一个请求都不发。

用 http2。首页要加载几十个资源，多路复用省掉的连接开销很可观。

剩下的 sendfile、open_file_cache 这些，是锦上添花。做不做差别不大，但既然配置一次就能长期生效，顺手做了也没什么坏处。

最后

静态博客的性能优化，本质上是在做两件事。让传输的数据更少，让重复的请求更少。

Nginx 提供了足够多的手段，但大部分默认值不是为静态站调的。花一个小时把这些配置过一遍，之后每一次访问都会受益。

折腾了三种博客程序之后，我最后还是回到了 Hugo

Tue, 12 Nov 2024 16:06:00 +0800

我的博客换过三次。

最早是 WordPress，插件装了一堆，功能确实全，但每次后台点一下都要等两三秒。那台 1 核 1G 的 VPS 跑 PHP 加 MySQL，内存常年飘在 90% 以上，隔三差五就被 OOM killer 干掉一次。

后来换 Hexo。静态生成，快是快，但 node_modules 那个目录，每次重装都像是在抽奖。有一次 npm install 装了两百多个包，其中一个包依赖的包又依赖别的包，最后卡在一个早就没人维护的模块上，编译失败。

再后来听人提 Hugo。我一开始觉得它就是个静态生成器，和 Hexo 差不多，没什么非换不可的理由。直到我看见有人用它构建几千篇文章只要几秒钟。

现在这个站跑在 Hugo 上，用了快一年，中间没有一次因为构建本身出问题。

装

Windows 上最省事的是用 scoop：

`1`	`scoop install hugo-extended`

一定要装 extended 版本。普通版本不支持 SCSS 和 Sass，而 Stack 主题的样式是用 SCSS 写的，装错版本会构建失败，报错信息还特别含糊。

Linux 上直接下二进制：

1
2
3

wget https://github.com/gohugoio/hugo/releases/latest/download/hugo_extended_linux-amd64.tar.gz
tar -xzf hugo_extended_linux-amd64.tar.gz
sudo mv hugo /usr/local/bin/

装完验证：

`1`	`hugo version`

输出里带 extended 字样就对了。

建站

1
2

hugo new site blog
cd blog

生成的目录结构是这样：

blog/
├── archetypes
├── assets
├── content
├── data
├── i18n
├── layouts
├── static
├── themes
└── hugo.toml

content 是文章，static 是原样拷贝的文件，themes 是主题。assets 这个目录值得说一下，放进去的东西会经过 Hugo 的管道处理，比如 SCSS 编译、图片压缩、JS 打包。

选主题

我试过好几个，最后停在 Stack 上。

它的视觉风格比较克制，左侧固定侧边栏，文章列表卡片式，暗色模式做得挺舒服。功能上该有的都有，标签、分类、归档、搜索、代码高亮、目录，不用自己补。

装主题有两种方式，submodule 和直接下载。submodule 干净一些：

1
2

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

用 submodule 之后，更新主题就是 git submodule update --remote，不会污染自己的仓库。

配置

hugo.toml 里最基本的东西：

baseURL = "https://blog.mibase.top/"
languageCode = "zh-cn"
title = "明月小站"
theme = "hugo-theme-stack"

[pagination]
  pagerSize = 10

[permalinks]
  posts = "/p/:slug/"

[markup]
  [markup.highlight]
    noClasses = false
    codeFences = true
    lineNos = false

[permalinks] 那段决定了文章的 URL 结构。我设成 /p/:slug/，是因为之前见过别人的站用日期做路径，文章一多，URL 长得没法记。用 slug 更短，也更容易分享。

注意 Hugo 从 0.128 开始把 paginate 改成了 pagination.pagerSize。老教程里写的 paginate = 10 现在会报警告。

Stack 主题还需要一份自己的配置，放在 config/_default/ 下面。主题仓库里的 exampleSite 目录有一份完整的示例，复制过来改最省事。

`1`	`cp -r themes/hugo-theme-stack/exampleSite/config/_default/* config/_default/`

然后改 config/_default/hugo.toml 里的 baseURL、title，改 params.toml 里的头像、社交链接、侧边栏设置。

写下第一篇

`1`	`hugo new content posts/hello-world/index.md`

注意这里写的是 posts/hello-world/index.md，不是 posts/hello-world.md。

这是 Hugo 的 Page Bundle 机制。用目录加 index.md 的形式，可以把图片和文章放在一起，引用的时候直接写相对路径：

`1`	`![截图](screenshot.png)`

不用管最终部署到哪个路径，Hugo 会自己处理。这个设计比把图片全塞进 static 里要好，因为文章和它的资源绑在一起，删文章的时候资源也跟着删，不会留下垃圾。

生成的 front matter 长这样：

---
title: "Hello World"
date: 2024-11-12T16:06:00+08:00
draft: true
---

draft: true 表示草稿，本地 hugo server 能看到，但构建的时候会被排除。写完改成 false 才会发布。

这个机制挺有用的。有时候写一半的东西不想让人看到，就留着 true，等写完再改。

本地预览

`1`	`hugo server -D`

-D 是显示草稿。默认只监听 localhost:1313，如果要让局域网里的手机也能看：

`1`	`hugo server -D --bind 0.0.0.0 --baseURL http://192.168.1.10:1313`

--baseURL 这个参数不加的话，手机打开页面样式是乱的，因为 css 的路径还指向 localhost。

Hugo 的 server 有热重载，改文章、改模板都会立刻刷新浏览器。改配置文件有时候需要重启，因为它不监听配置文件的变化。

构建

`1`	`hugo --minify --gc`

产物在 public 目录。

--minify 会压缩 html、css、js 和 json，一般能小 20% 左右。--gc 清理掉不再被引用的缓存文件，防止 resources 目录无限膨胀。

有个参数我一开始不知道，--printPathWarnings，它会告诉你哪些页面有重复路径。文章多了之后很有用，能提前发现 slug 冲突。

部署

我把 public 目录通过 git 钩子同步到服务器，那套流程写在另一篇里了。简单说就是本地 push，服务器上的钩子执行 hugo 构建，nginx 指向产物目录。

这个方案的好处是不需要额外的 CI 服务，坏处是构建在服务器上跑，服务器得装 Hugo。我服务器上装的是 extended 版本，和本地保持一致。

目录约定

用了一段时间，我把目录固定成了这样：

content/
├── page/
│   ├── about/index.md
│   └── links/index.md
└── posts/
    ├── hello-world/index.md
    └── another-post/index.md

posts 下面全是文章，一篇一个目录。page 下面放独立页面，比如关于、友链。Stack 主题默认就是这么分的。

分类和标签不用建目录，写在 front matter 里就行，Hugo 会自动生成列表页。

一个容易踩的坑

Hugo 的 date 字段如果没有时区，会按 UTC 解释。

我第一篇文章写的是 date: 2024-11-12 16:06:00，构建出来发现时间比实际早了八小时。后来改成带时区的格式 2024-11-12T16:06:00+08:00 才对。

这个在本地看不出来，因为 hugo server 用的是本地时区。部署到服务器上，服务器是 UTC，就露馅了。

现在回头看

三次换博客程序，每次的动机都不一样。

WordPress 是图省事，Hexo 是图轻快，Hugo 是图稳定。

现在这套东西，构建三秒，部署十秒，改一行配置立刻能看到效果。中间没有数据库，没有后台，没有需要重启的服务。它就是一堆文件。

这种简单带来的安心感，是前面两个方案没给过我的。

一些我后来才明白的细节

hugo.toml 里的 baseURL 结尾一定要带斜杠。写成 https://blog.mibase.top 而不是 https://blog.mibase.top/，生成的 rss 和 sitemap 里的链接会缺一个斜杠，有些抓取工具会因此报错。

content 目录下以 _index.md 开头的文件是列表页，不是文章。posts/_index.md 定义了文章列表页的标题和排序方式。如果你不小心把文章命名成 _index.md，它不会出现在文章列表里，反而会变成那个目录的列表页。

草稿的 draft: true 只影响构建，不影响 hugo server。只要加了 -D，草稿一样能看到。有时候我写完忘了改，本地看着好好的，部署上去发现没有这篇，才想起来。

resources/_gen 这个目录是 Hugo 的缓存，可以删，删了会重新生成。但它不要提交到 git 里，会污染 diff。.gitignore 里加上这一行：

1
2

resources/_gen/
public/

public 也不该提交。它是构建产物，每次部署都会重新生成，提交进去只会让仓库变大。

如果重新来一次

我会在第一天就把这些东西配好，而不是用了半年才补。

hugo.toml 里的 enableRobotsTXT，加上之后会自动生成 robots.txt。

[markup.goldmark.renderer] 里的 unsafe = true，加上之后才能在文章里直接写 html。默认是关闭的，是为了安全，但自己的博客自己写内容，没什么风险。

[outputs] 里给首页加上 JSON，这样才有搜索用的 index.json。Stack 的搜索依赖这个。

这些都是一次性的配置，配好之后就不用管了。但不知道的时候，会卡很久。