从零搭建 Hugo + PaperMod 博客之一：新建站点和本地预览

前言

一、为什么要写博客

开始搭建博客之前，我也想过：现在还有必要写博客吗？信息爆炸的时代，短视频、社交媒体、知识付费平台无处不在，一个个人博客似乎显得过于"古典"。但换个角度想一想，也许你会发现博客的价值恰恰在于它的"慢"和"沉淀"。

博客首先是一种记录与整理。日常生活中的点滴感悟、某本书的读后感、旅行中的见闻，如果不及时记录下来，往往转瞬即逝。而对于技术人员，一个棘手的 Bug、一次项目重构的得失、一门新技术的学习心得，如果只是靠大脑记忆，往往过一段时间就忘了个大概。写博客的过程，就是把零散的想法整理成连贯的文字，把模糊的感觉提炼成清晰的观点。长期坚持，个人的逻辑能力和语言组织能力会在不知不觉中提升。当时的随手留存，时间会赋予它们意外的重量。

博客也是一种分享与连接。当你试图把一件事讲清楚时，你会发现自己原来还有很多盲点，这种"教是最好的学"的过程，本身就是对知识的系统梳理。而这些文章发布到互联网上，可能会帮到正在搜索引擎里寻找答案的另一个人，也可能吸引到有相同兴趣的读者，这种基于具体内容质量的连接，往往比社交媒体上的泛泛之交更加深入。

日积月累，博客不仅留下了一份珍贵的人生档案，也成为一份持续更新的个人履历——面试官或合作伙伴可以通过你的文章，直观地看到你的技术深度、表达能力和持续学习的习惯。

2、三方自媒体平台便利与自主掌控的取舍

微信公众号、知乎专栏、技术社区、短视频平台……如今的自媒体生态确实提供了极大的便利。注册即发布，内容自带推荐流量，互动与数据统计一应俱全。然而，便利的代价往往是让渡控制权。

在第三方平台上，内容的所有权并不完全属于创作者。你的内容本质上是在"借地耕种"。审核边界、流量分配规则、甚至账号状态，都掌握在平台手中。更现实的是，平台通常不提供完整的数据导出通道，排版受限于固定模板，长期来看，服务调整、链接失效或账号异常的风险始终存在。你的心血可能因为一次规则更新或服务器迁移而难以找回。

自建博客则像是一场自主建房的过程。前期需要熟悉命令行、版本控制与静态部署，但换来的是对内容的绝对掌控。你可以自由决定写什么、如何排版、何时修改；所有源文件都保存在本地，通过 Git 即可完整备份；只要你愿意，站点就能穿越平台周期长久存在。此外，搭建过程本身也是一次低门槛的技术实践，顺便熟悉了现代前端工作流与自动化部署逻辑。

这种自主权也延伸到了写作格式与阅读体验上。自建博客通常使用 Markdown 格式，支持代码高亮、数学公式、自定义样式，对技术写作极为友好，

其实这并非非此即彼的选择，三方平台与自建博客并不冲突，我们完全可以采用双轨策略：让二者优势互补。

三、为什么选择 Hugo

静态网站生成器有很多，Hexo、Jekyll、VuePress、Astro 等等，为什么我最终选择了 Hugo？

1. 极致的构建速度

Hugo 是用 Go 语言编写的，号称"世界上最快的静态网站生成器"。对于几百篇文章的博客，Hugo 的构建时间通常以毫秒计。这意味着本地预览几乎是瞬时的，写作-预览-发布的循环非常流畅。

2. 单二进制文件，部署简单

Hugo 是一个单文件可执行程序，没有复杂的依赖。无论是在本地写作，还是在 CI/CD 流水线中自动构建，都只需要一个二进制文件即可。这种简洁性大大降低了维护成本。

3. Markdown 原生支持，写作体验纯粹

Hugo 的内容全部使用 Markdown 格式。你可以用任何喜欢的编辑器（VS Code、Vim、Obsidian 甚至纯文本编辑器）来写作，不需要忍受在线富文本编辑器的卡顿和格式错乱。配合 Git 版本控制，每一篇文章的修改历史都清晰可追溯。

4. 丰富的主题生态与高度可定制

Hugo 拥有庞大的主题市场，从极简的 PaperMod 到功能完备的 Docsy，几乎可以满足任何审美需求。更重要的是，Hugo 的模板引擎基于 Go 的 html/template，逻辑清晰、性能优异，当你需要深度定制时，不会感到束手束脚。

5. 与现代托管平台无缝集成

Hugo 生成的只是一堆静态文件（HTML、CSS、JS），这意味着它可以托管在任何支持静态文件的服务上：GitHub Pages、Cloudflare Pages、Vercel、Netlify，甚至你自己的服务器。这种灵活性让你可以随时迁移，不会被任何服务商锁定。

四、这个系列会讲什么

本系列记录在 Windows 环境下，使用 Hugo 与 PaperMod 主题从零搭建个人博客的完整流程。内容以可复现的步骤为主，涵盖环境安装、站点初始化、主题配置、文章撰写、体验优化与最终部署。除基础搭建篇外，后续的样式调整与功能增强均为可选项，读者可根据实际需求自由取舍。

我希望这个系列不仅是一份技术教程，更是一份"数字花园"的搭建指南。无论你是技术从业者，还是单纯想拥有一个属于自己的写作空间，都可以跟着这个系列一步步操作。

最后，我想引用一句话：

“博客不是写给世界的，而是写给自己的；但正因为写给了自己，它才意外地连接了世界。”

如果你也厌倦了在算法推荐的信息流中被动接收内容，如果你也想在互联网上拥有一块真正属于自己的一小块土地，那么，让我们一起开始吧。

一、环境准备：安装 Hugo

1.1 下载 Hugo

官方发布页：https://github.com/gohugoio/hugo/releases
务必选择 extended 版本（文件名含 extended），否则 SCSS 编译、图片处理等功能不可用
本文当前使用的是：hugo_extended__0.161.1_windows-amd64.zip

1.2 安装与验证

将下载的压缩包解压到任意位置，最好不含空格与中文字符，然后将hugo.exe 所在路径添加到系统 Path 环境变量（注意是 hugo.exe 所在路径，不是 hugo.exe 本身）。

或者也可以解压后将 hugo.exe 移至系统路径，比如 C:\Windows\。

验证安装

cmd
hugo version
:: 预期输出包含：版本号- ... +extended windows/amd64

小技巧：若 hugo 命令未识别，请检查环境变量 Path 是否已包含 exe 所在目录。

二、创建新站点

可选但建议首先安装 git bash，可在 git 官网下载。

cmd
:: 创建站点目录（路径不含中文/空格更稳妥）
hugo new site myblog --force
cd myblog

:: 初始化 Git（推荐，便于主题管理与后续部署）
git init

文件/目录	描述
hugo.toml	全局配置文件
archetypes	存储以Markdown格式的内容模板
content	存储网页内容，如文章等
layouts	存储定义网站结构的HTML文件
themes	存储主题模板文件
data	存储生成网站页面所需的补充数据(JSON、YAML或TOML格式)
static	存储不需要任何额外处理的静态资源，如音视频、图片，字体，DNS验证文件等

三、安装 PaperMod 主题

推荐使用 Git submodule 方式安装，便于后续更新：

cmd
git submodule add git@github.com:adityatelange/hugo-PaperMod.git themes/PaperMod
:: 或者
git submodule add https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod
:: 以上二选一，更推荐使用前者 ssh 协议更稳定

注意：若提示权限错误，请以管理员身份运行 CMD，或检查目录写入权限。

四、核心配置：hugo.toml

项目根目录的 hugo.toml 是新建站点的配置文件，以下示例配置可以全部替换，也可以按需参考修改。此配置已针对中文博客优化，并启用搜索、目录、代码复制等实用功能：

toml
baseURL = 'https://example.org/' # 部署时替换成你自己的实际域名
title = '你的博客名称'
theme = "PaperMod"
defaultContentLanguage = "zh"

hasCJKLanguage = true
enableRobotsTXT = true
enableEmoji = true

# 输出格式（搜索功能必需）
[outputs]
  home = ["HTML", "RSS", "JSON"]
  page = ["HTML"]

# 语言配置（Hugo 0.158+ 标准写法）
[languages]
  [languages.zh]
    locale = "zh-CN"
    title = "你的博客名称"
    weight = 1

# Markdown 与语法高亮配置
[markup]
  [markup.goldmark]
    [markup.goldmark.renderer]
      unsafe = true
  [markup.highlight]
    noClasses = false
    codeFences = true
    guessSyntax = true
    lineNos = false
    lineNumbersInTable = true
    style = "monokai"
  [markup.tableOfContents]
    startLevel = 2
    endLevel = 4
    ordered = false

# 全局参数配置
[params]
  env = "production"
  description = "记录技术笔记、生活随笔与日常思考的个人博客"
  author = "你的名字"
  hideAuthor = true
  DateFormat = "2006-01-02"
  defaultTheme = "auto"
  disableThemeToggle = false
  ShowRssButtonInSectionTermList = true

  # 文章显示选项
  ShowReadingTime = true
  ShowWordCount = true
  ShowBreadCrumbs = true
  ShowCodeCopyButtons = true
  ShowPostNavLinks = true
  ShowToc = true
  TocOpen = false

  # 首页信息
  [params.profileMode]
    enabled = false
  [params.homeInfoParams]
    Title = "首页展示信息标题"
    Content = "博客简介"

  # 封面图策略
  [params.cover]
    hiddenInList = false
    hiddenInSingle = true

  # 搜索优化（Fuse.js）
  [params.fuseOpts]
    isCaseSensitive = false
    shouldSort = true
    location = 0
    distance = 1000
    threshold = 0.4
    minMatchCharLength = 0
    keys = ["title", "permalink", "summary"]

  # 社交图标
  [[params.socialIcons]]
    name = "email"
    url = "mailto:name@example.com"
  [[params.socialIcons]]
    name = "rss"
    url = "index.xml"

# 导航菜单
[[menu.main]]
  identifier = "home"
  name = "首页"
  pageRef = "/"
  weight = 1
[[menu.main]]
  identifier = "posts"
  name = "文章"
  pageRef = "/posts/"
  weight = 2
[[menu.main]]
  identifier = "series"
  name = "系列"
  pageRef = "/series/"
  weight = 3
[[menu.main]]
  identifier = "archives"
  name = "归档"
  pageRef = "/archives/"
  weight = 4
[[menu.main]]
  identifier = "categories"
  name = "分类"
  pageRef = "/categories/"
  weight = 5
[[menu.main]]
  identifier = "search"
  name = "搜索"
  pageRef = "/search/"
  weight = 7
[[menu.main]]
  identifier = "about"
  name = "关于"
  pageRef = "/about/"
  weight = 50

# 分类系统
[taxonomies]
  category = "categories"
  tag = "tags"
  series = "series"

说明：

hasCJKLanguage = true 确保中文字数统计准确
outputs.home 包含 JSON 是启用本地搜索的前提
markup.highlight.noClasses = false 配合 PaperMod 的内置代码高亮样式
菜单 weight 值决定显示顺序，数值越小越靠前

五、创建必要页面

5.1 归档页

cmd
hugo new archives.md

编辑 content/archives.md：

markdown
---
title: "归档"
layout: "archives"
url: "/archives/"
summary: "按时间排序的所有文章"
---

5.2 搜索页

cmd
hugo new search.md

编辑 content/search.md：

markdown
---
title: "搜索"
layout: "search"
placeholder: "输入关键词..."
---

5.3 系列页

cmd
hugo new series.md

编辑 content/series.md：

markdown
---
title: "系列"
layout: "taxonomies"
url: "/series/"
type: "series"
---

5.4 分类页

cmd
hugo new categories.md

编辑 content/categories.md：

markdown
---
title: "分类"
layout: "taxonomies"
url: "/categories/"
type: "categories"
---

5.5 关于页

cmd
hugo new about.md

编辑 content/about.md，填写个人或博客简介即可。

6、本地预览与构建

cmd
:: 启动开发服务器（自动重载，包含草稿和未来日期文章）
hugo server -D -F

:: 浏览器访问：http://localhost:1313

:: 生产构建（压缩 + 清理冗余）
hugo --minify --gc
:: 输出目录：./public

提示：-D 包含草稿，-F 包含未来日期文章，开发时方便预览；生产构建请移除这两个参数。

7、常见问题速查

问题	可能原因	解决方案
`hugo: command not found`	环境变量未配置	将 `hugo.exe` 所在目录加入 `Path`
主题样式未生效	未使用 extended 版本	重新下载含 `extended` 的 Hugo
搜索框无结果	缺少 JSON 输出	检查 `[outputs]` 是否含 `JSON`
中文标签乱码	文件编码非 UTF-8	用 VSCode 保存为 `UTF-8 without BOM`
Git submodule 失败	路径过长或权限不足	启用 `git config --system core.longpaths true` 或以管理员运行
系列/分类页面空白	未创建对应 layout 页面	确认 `content/series.md` 等文件包含正确的 `layout` 和 `type`

参考资源

PaperMod 官方 Wiki：https://github.com/adityatelange/hugo-PaperMod/wiki
Hugo 官方文档：https://gohugo.io/documentation/
TOML 配置语法：https://toml.io/
Fuse.js 搜索配置参考：https://fusejs.io/api/options.html

最后建议：先跑通「最小可用博客」，再逐步添加自定义样式。技术博客的核心是内容，样式是锦上添花。

前言#

一、为什么要写博客#

2、三方自媒体平台便利与自主掌控的取舍#

三、为什么选择 Hugo#

四、这个系列会讲什么#

一、环境准备：安装 Hugo#

1.1 下载 Hugo#

1.2 安装与验证#

二、创建新站点#

三、安装 PaperMod 主题#

四、核心配置：hugo.toml#

五、创建必要页面#

5.1 归档页#

5.2 搜索页#

5.3 系列页#

5.4 分类页#

5.5 关于页#

6、本地预览与构建#

7、常见问题速查#

参考资源#

评论

前言