Hugo

起因 上一篇文章里说过我想开个博客记录学习——这篇讲博客本身是怎么搭起来的，以及搭建过程中真实踩过的几个坑。 技术栈选得很朴素：Hugo（静态站点生成器）+ PaperMod（主题）+ GitHub Pages（托管）+ Giscus（评论，底层是 GitHub Discussions）。 理论上这套 30 分钟能搞定的事，实际花了整整一个下午加一个晚上——其中大半时间耗在一个看似配置都对、但 Giscus 死活报 Unable to create discussion 的问题上。 下面按踩坑顺序记录。 1. 一波加 16 个 feature，让 agent 并行做 第一篇文章发出去之后，我列了一堆功能需求： 系列文章（taxonomy + 首页云 + 前后篇导航） 搜索框点击 bug 首页 taxonomy 云（分类 + 标签） 自定义 shortcode（alert / card / video） 代码语法高亮（chroma CSS） 代码块复制按钮 Giscus 评论 Mermaid 流程图 + KaTeX 数学公式 分享按钮（微博 + 复制链接） 多语言支持（加英文） 彩虹标签 图标科技感 …… 一共 16 项。我派了 11 个 agent 同时干，每只 agent 拿到独立的文件范围，互不重叠，跑完自己 commit + push。 ...

本文是 Hugo + PaperMod 博客搭建：从 0 到评论上线，我踩过的坑 的「完整版」——上篇是叙事版，这篇是参考手册版。读这一篇就能掌握搭建这个博客用到的全部 Hugo 知识。 1. 什么是 Hugo Hugo 是一个用 Go 写的静态站点生成器（Static Site Generator, SSG）。你写 Markdown，Hugo 编译成 HTML，浏览器直接读 HTML 文件。 跟同类对比： 工具 语言 特点 Hugo Go 快——几千页也毫秒级编译 Jekyll Ruby 老牌，GitHub Pages 原生支持 Hexo Node.js 中文社区多 Gatsby React + GraphQL 适合复杂前端 Astro 多框架 现代，新兴 Hugo 的最大卖点是速度——几千篇文章的站，一次完整 build 通常 < 1 秒。本地 hugo server 改一行就热更新，几乎无感。 ℹ️Info > Hugo 是「无依赖」工具——单文件可执行（~30 MB），不装 Node、不装 Ruby、不装数据库。丢任何机器上都能跑。 > 2. 安装 macOS 1 brew install hugo Linux 1 2 3 4 5 # Debian/Ubuntu sudo apt install hugo # 或最新版（推荐） snap install hugo --channel=extended ⚠️Warning > 装 **`extended`** 版本——后面要用 Hugo Pipes 处理 SCSS，普通版不支持。 > Windows 1 2 choco install hugo-extended # 或 scoop install hugo-extended 验证 1 2 hugo version # hugo v0.158.0+extended ... 3. 初始化一个新站 1 2 hugo new site my-blog cd my-blog 生成结构： ...