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

前言

Hugo 是 Go 语言编写的静态网站生成器，速度快，易用，可配置。作为一款跨平台开源建站系统，当前提供 Windows，Linux，FreeBSD，NetBSD 和 OS X (Darwin) 的 x 64, i 386 和 ARM 架构的二进制预构建包。

Hugo 依赖于 Markdown 文件，元数据字体。用户可以从任意的目录中运行 Hugo，支持共享主机和其他系统。只需要几分之一秒就可以渲染一个经典的中小型网站，非常适合博客，文档等等网站的生成。

本文记录在 Windows 环境下使用 Hugo + PaperMod 主题从零搭建静态博客的完整流程。目标：步骤完整、配置可复现、语言简洁。快速完成基础搭建。

一、环境准备：安装 Hugo

1.1 下载 Hugo

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

1.2 安装与验证

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

或者也可以解压后将 hugo.exe 移至系统路径，例如：

cmd
move hugo.exe C:\Windows\

:: 验证安装
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

注意：若提示权限错误，请以管理员身份运行 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

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

前言#

一、环境准备：安装 Hugo#

1.1 下载 Hugo#

1.2 安装与验证#

二、创建新站点#

三、安装 PaperMod 主题#

四、核心配置：hugo.toml#

五、创建必要页面#

5.1 归档页#

5.2 搜索页#

5.3 系列页#

5.4 分类页#

5.5 关于页#

6、本地预览与构建#

7、常见问题速查#

参考资源#

评论

前言