用 Hugo + Nginx 搭建静态技术笔记站点

为什么选静态站点

技术笔记的核心诉求是：写作成本低、渲染稳定、长期可访问。静态站点生成器把 Markdown 编译成纯 HTML，部署后无需运行时、无数据库、无依赖，正好满足这三点。Hugo 以 Go 编写，单二进制、构建速度极快（数千页在亚秒级完成），是最省心的选择。

目录结构

一个最小可用的 Hugo 站点如下：

/opt/www/dshost
├── hugo.toml
├── content/
│   ├── about.md
│   └── posts/
│       └── 2026-08-20-hugo-nginx-static-deploy.md
├── layouts/            # 覆盖主题模板（页脚、首页）
├── themes/minimal/     # 主题
└── public/             # 构建产物（Nginx 根目录）

关键配置

hugo.toml 中需要固定三件事：站点的 baseURL、文章的永久链接格式、以及 Goldmark 的 unsafe 渲染（允许原始 HTML，便于插入代码与图表）。

baseURL = 'https://dshost.me'
title = 'dsh技术笔记'

[permalinks]
  posts = '/:year/:month/:slug/'

[markup]
  [markup.goldmark.renderer]
    unsafe = true

Nginx 托管

Nginx 直接以 public/ 为根目录，对静态资源设置长缓存，并把 80 端口全部 301 到 HTTPS：

root /opt/www/dshost/public;
index index.html index.htm;

location / {
    try_files $uri $uri/ =404;
    location ~* \.(css|js|png|jpg|jpeg|gif|ico|svg|woff|woff2)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

构建与发布

Hugo 的构建是一条命令，minify 后产物即可被 Nginx 直接服务：

cd /opt/www/dshost && hugo --minify

为减少人为失误，把构建封装成 publish.sh：进入目录、执行 hugo –minify、检查退出码。新增文章只需把 Markdown 放入 content/posts/，再跑一次脚本。整条链路无数据库、无运行时，五年后仍能原样打开。