Hugo 静态网站构建实战手册

配置管理

掌握 Hugo 配置文件、环境配置、菜单、分页、输出格式、分类法和常用站点参数

配置管理

Hugo 的配置决定站点地址、语言、主题、分页、菜单、输出格式、分类法、资源处理和主题参数。小站可以只用一个 hugo.toml，大站建议拆分到 config/ 目录。

配置文件格式

Hugo 支持三种格式：

hugo.toml
hugo.yaml
hugo.json

本文统一使用 TOML。TOML 对 Hugo 项目很友好，层级清晰，注释方便。

最小配置

baseURL = 'https://example.org/'
title = '我的 Hugo 站点'
theme = 'ananke'
defaultContentLanguage = 'zh'
languageCode = 'zh-CN'

说明：

  • baseURL 是线上站点根地址，影响绝对链接、RSS、Sitemap 等输出
  • title 是站点标题
  • theme 是主题目录名或模块名
  • defaultContentLanguage 是默认内容语言
  • languageCode 是传统语言代码配置；新版本 Hugo 更推荐配合 languages 使用 languageCode 和 languageName 等语言参数，日期本地化可使用 locale

推荐基础配置

baseURL = 'https://example.org/'
title = '我的博客'
theme = 'ananke'
defaultContentLanguage = 'zh'
languageCode = 'zh-CN'
hasCJKLanguage = true
enableRobotsTXT = true
summaryLength = 120

[pagination]
  pagerSize = 10

[params]
  description = '记录技术、生活和长期学习'
  author = '你的名字'

hasCJKLanguage = true 对中文摘要和字数统计更友好。

config/ 目录拆分

当配置变多时，可以拆成多个文件：

config/
└── _default/
    ├── hugo.toml
    ├── menus.toml
    ├── params.toml
    ├── outputs.toml
    └── taxonomies.toml

示例：

# config/_default/hugo.toml
baseURL = 'https://example.org/'
title = '我的博客'
theme = 'ananke'
defaultContentLanguage = 'zh'
languageCode = 'zh-CN'

# config/_default/params.toml
description = '记录技术、生活和长期学习'
author = '你的名字'

拆分后更适合长期维护，也方便主题文档把配置按功能归类。

环境配置

Hugo 支持不同环境的配置覆盖：

config/
├── _default/
│   └── hugo.toml
├── development/
│   └── hugo.toml
└── production/
    └── hugo.toml

开发环境：

# config/development/hugo.toml
baseURL = 'http://localhost:1313/'
buildDrafts = true
buildFuture = true

生产环境：

# config/production/hugo.toml
baseURL = 'https://example.org/'
minify = true

指定环境构建：

hugo --environment production
hugo server --environment development

菜单配置

菜单可以写在配置文件里，也可以写在页面 Front Matter 中。

配置文件方式

[[menus.main]]
  name = '首页'
  pageRef = '/'
  weight = 10

[[menus.main]]
  name = '文章'
  pageRef = '/posts'
  weight = 20

[[menus.main]]
  name = '关于'
  pageRef = '/about'
  weight = 90

优先使用 pageRef 指向站内页面，它比手写 URL 更稳。

Front Matter 方式

---
title: "关于"
menu:
  main:
    name: "关于"
    weight: 90
---

适合少量固定页面。

分类法配置

默认常见分类法是 tags 和 categories。你也可以添加 series。

[taxonomies]
  tag = 'tags'
  category = 'categories'
  series = 'series'

文章中使用：

---
title: "Hugo 模板笔记"
categories: ["Hugo"]
tags: ["模板", "静态网站"]
series: ["Hugo 实战"]
---

Hugo 会生成类似页面：

/tags/模板/
/categories/hugo/
/series/hugo-实战/

输出格式

Hugo 可以为不同页面类型配置输出格式：

[outputs]
  home = ['HTML', 'RSS', 'JSON']
  section = ['HTML', 'RSS']
  taxonomy = ['HTML', 'RSS']
  term = ['HTML', 'RSS']
  page = ['HTML']

如果主题提供搜索功能，通常会要求首页输出 JSON：

[outputFormats.Search]
  mediaType = 'application/json'
  baseName = 'search'
  isPlainText = true

[outputs]
  home = ['HTML', 'RSS', 'Search']

具体字段要以主题模板为准。

分页配置

新版本 Hugo 推荐使用 [pagination]：

[pagination]
  pagerSize = 10
  path = 'page'

输出效果：

/posts/
/posts/page/2/
/posts/page/3/

在模板中常见写法：

{{ $paginator := .Paginate .Pages }}
{{ range $paginator.Pages }}
  <h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2>
{{ end }}

URL 规则

可以为不同栏目配置 URL：

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

文章 Front Matter 中建议设置 slug：

---
title: "Hugo 配置管理"
slug: "hugo-configuration"
---

uglyURLs

默认输出是漂亮链接：

/posts/hello/

如果开启：

uglyURLs = true

会输出：

/posts/hello.html

除非部署环境有特殊要求，一般保持默认即可。

Markdown 渲染配置

Hugo 使用 Goldmark 渲染 Markdown。常见配置：

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

  [markup.highlight]
    noClasses = false
    style = 'github'
    lineNos = false

如果文章中需要直接写 HTML：

[markup.goldmark.renderer]
  unsafe = true

开启前要确认内容来源可信。

图片处理配置

[imaging]
  quality = 80
  resampleFilter = 'lanczos'
  anchor = 'smart'

模板中处理图片：

{{ with .Resources.GetMatch "cover.*" }}
  {{ $cover := .Fill "1200x630 webp" }}
  <img src="{{ $cover.RelPermalink }}" alt="{{ $.Title }}">
{{ end }}

sitemap 与 robots

enableRobotsTXT = true

[sitemap]
  changeFreq = 'weekly'
  priority = 0.5
  filename = 'sitemap.xml'

如果主题没有自定义 robots.txt，Hugo 会生成基础版本。

安全配置

Hugo 默认限制模板读取环境变量和执行外部程序。需要在 CI 中读取变量时可以配置白名单：

[security]
  [security.funcs]
    getenv = ['^HUGO_', '^CI$']

不要为了省事放开所有环境变量。

主题参数

params 是主题最常读取的配置区域。不同主题字段不同，以主题文档为准。

[params]
  description = '我的个人博客'
  mainSections = ['posts']

  [params.author]
    name = '你的名字'
    avatar = '/images/avatar.jpg'
    bio = '记录长期学习'

模板中读取：

{{ site.Params.description }}
{{ site.Params.author.name }}

命令行覆盖配置

临时指定参数：

hugo --baseURL https://example.org/ --minify
hugo server -D --port 8080

查看最终配置：

hugo config
hugo config --format json

排查配置问题时，hugo config 比肉眼检查多个文件更可靠。

配置建议

  • 个人小站可以先用单个 hugo.toml
  • 配置超过两百行后，拆分到 config/_default/
  • 线上部署固定 Hugo 版本
  • baseURL 必须和线上地址一致
  • 主题参数只写主题实际使用的字段
  • 不要把密钥写入仓库，使用平台环境变量

下一步

继续阅读 内容管理，把配置和真实内容组织起来。

评论

0%