Hugo 博客框架详解：最快的静态网站生成器

前言

在上一篇系列文章中，我们深入讲解了 Hexo 博客框架。本文将介绍另一个备受推崇的静态网站生成器 —— Hugo。Hugo 以"快"著称，能够在毫秒级别生成数千篇文章的站点，是大型博客和文档站点的理想选择。

为什么选择 Hugo？

Hugo vs Hexo 对比

特性	Hugo	Hexo
编写语言	Go	Node.js
安装方式	单文件二进制	npm 全局安装
生成速度	极快（~1000 页/秒）	快（~10-50 页/秒）
依赖管理	无需依赖	需要 Node.js 和 npm
内容组织	灵活（支持多种内容类型）	简单（主要是文章）
多语言支持	原生支持	需插件
学习曲线	中等	低

Hugo 的核心优势

速度极快：Go 语言的并发特性使 Hugo 的生成速度无人能及
零依赖：下载一个二进制文件即可使用，无需安装 Node.js 或 Ruby
功能强大：内置多语言、分页、分类、标签、内容摘要等功能
主题丰富：官方主题库有数百个高质量主题
活跃维护：由 Go 社区维护，更新频繁

安装 Hugo

Windows 安装

方法一：使用 Chocolatey

choco install hugo -y

方法二：使用 Scoop

scoop install hugo

方法三：手动安装

访问 Hugo Releases
下载 hugo_extended_*_Windows-64bit.zip
解压后将 hugo.exe 放到 PATH 环境变量包含的目录中

macOS 安装

# 使用 Homebrew
brew install hugo

# 或使用 MacPorts
sudo port install hugo

Linux 安装

# Ubuntu/Debian
sudo apt update
sudo apt install hugo

# 或从 GitHub 下载最新版
wget https://github.com/gohugoio/hugo/releases/download/v0.147.0/hugo_extended_*_Linux-64bit.tar.gz
tar -xzf hugo_*_Linux-64bit.tar.gz
sudo mv hugo /usr/local/bin/

验证安装

hugo version

快速开始

创建新站点

hugo new site my-blog
cd my-blog

目录结构：

my-blog/
├── archetypes/         # 内容模板
│   └── default.md
├── assets/            # 源资源文件（CSS、JS 等）
├── content/           # 内容目录（重要！）
│   └── posts/         # 文章目录
├── data/              # 数据文件
├── i18n/              # 国际化文件
├── layouts/           # 布局模板
├── static/            # 静态资源（直接复制）
├── themes/            # 主题目录
├── hugo.toml          # 配置文件（或 config.toml / config.yaml）
└── README.md

添加主题

# 使用 Git 子模块添加主题（推荐）
git init
git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke

# 在配置中启用主题
echo "theme = 'ananke'" >> hugo.toml

创建第一篇文章

hugo new posts/my-first-post.md

编辑 content/posts/my-first-post.md：

---
title: "My First Post"
date: 2021-11-01T10:00:00+08:00
draft: true
---

这是我的第一篇文章！

启动本地服务器

hugo server -D

访问 http://localhost:1313 查看博客。

-D 参数表示显示草稿文章（draft: true），正式发布时去掉该参数。

生成静态文件

hugo

生成的静态文件位于 public/ 目录下。

配置文件详解

Hugo 支持 yaml、toml、json 三种配置格式，推荐使用 hugo.toml（TOML 格式）。

基础配置示例

# hugo.toml

# 基本设置
baseURL = 'https://yourdomain.com/'
languageCode = 'zh-CN'
title = '我的 Hugo 博客'
theme = 'ananke'

# 构建配置
buildFuture = false
buildExpired = false
buildDrafts = false

# 内容设置
defaultContentLanguage = 'zh-CN'
paginate = 10

# 菜单配置
[[menu.main]]
  identifier = "home"
  name = "首页"
  url = "/"
  weight = 1

[[menu.main]]
  identifier = "posts"
  name = "文章"
  url = "/posts/"
  weight = 2

[[menu.main]]
  identifier = "tags"
  name = "标签"
  url = "/tags/"
  weight = 3

内容组织

页面包（Page Bundle）

Hugo 支持两种内容组织方式：

1. 独立文件方式

content/
├── posts/
│   ├── post-1.md
│   └── post-2.md

2. 页面包方式（推荐）

content/
├── posts/
│   ├── post-1/
│   │   ├── index.md      # 文章内容
│   │   ├── image1.png    # 文章资源
│   │   └── image2.jpg
│   └── post-2/
│       └── index.md

页面包方式的优势：资源文件和文章在一起，便于管理。

Front Matter

Hugo 的 front matter 支持 YAML、TOML、JSON 三种格式：

---
title: 文章标题
date: 2021-11-01
lastmod: 2021-11-15
draft: false
author: 作者名
tags: [Hugo, 静态网站]
categories: [编程]
description: 文章描述
weight: 1
---

短代码（Shortcodes）

Hugo 提供了短代码功能，可以在 Markdown 中嵌入复杂内容：

<!-- 嵌入 YouTube 视频 -->
{{< youtube w7Ft2ymGmfc >}}

<!-- 嵌入图片（支持页面包资源） -->
{{< figure src="image.png" title="图片标题" >}}

<!-- 内部链接 -->
{{< ref "another-post.md" >}}

<!-- 高亮代码块 -->
{{< highlight go "linenos=table" >}}
func main() {
    fmt.Println("Hello, Hugo!")
}
{{< /highlight >}}

主题系统

安装主题

方法一：Git 子模块（推荐）

git submodule add https://github.com/theme-author/theme-name.git themes/theme-name

方法二：下载解压

cd themes
git clone https://github.com/theme-author/theme-name.git

主题	特点	适用场景
Ananke	简洁通用	个人博客
PaperMod	极简风格	技术博客
LoveIt	功能丰富	综合博客
Docsy	文档风格	技术文档
Blowfish	现代化	个人站点

自定义主题

Hugo 使用 Hugo Blocks 和 Partial Templates 实现主题定制：

layouts/
├── _default/
│   ├── baseof.html      # 基础布局模板
│   ├── list.html        # 列表页模板
│   └── single.html      # 文章页模板
├── partials/
│   ├── head.html        # 头部部分
│   ├── header.html      # 页头部分
│   └── footer.html      # 页脚部分

多语言支持

Hugo 原生支持多语言站点：

# hugo.toml
defaultContentLanguage = 'zh'
languages:
  zh:
    languageName: '中文'
    weight: 1
    title: '我的博客（中文）'
  en:
    languageName: 'English'
    weight: 2
    title: 'My Blog (English)'

创建对应语言的内容：

content/
├── posts/           # 中文文章（默认语言）
│   └── hello.md
└── en/
    └── posts/       # 英文文章
        └── hello.md

部署到 GitHub Pages

方法一：手动部署

# 生成静态文件
hugo -d docs

# 提交到 GitHub
git add .
git commit -m "Deploy site"
git push origin main

在 GitHub 仓库设置中，将 Pages 的 Source 设置为 docs 目录。

方法二：GitHub Actions 自动部署

创建 .github/workflows/hugo-deploy.yml：

name: Deploy Hugo Site

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          submodules: recursive

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v3
        with:
          hugo-version: 'latest'
          extended: true

      - name: Build
        run: hugo --minify

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public

常用 Hugo 命令

命令	说明
`hugo new site <name>`	创建新站点
`hugo new <path>`	创建新内容
`hugo server`	启动本地服务器
`hugo server -D`	启动本地服务器（包含草稿）
`hugo server --buildFuture`	包含未来日期的文章
`hugo`	生成静态文件
`hugo --minify`	生成并压缩静态文件
`hugo list drafts`	列出所有草稿
`hugo list future`	列出未来日期的文章

常见问题

问题1：主题不生效

解决：确认 hugo.toml 中 theme 设置正确，且主题已下载到 themes/ 目录。

问题2：图片不显示

解决：

如果是页面包方式，使用 {{< figure src="image.png" >}}
如果是独立文件方式，图片应放在 static/ 目录下，使用 /image.png 引用

问题3：草稿文章不显示

解决：本地预览时添加 -D 参数：hugo server -D

总结

Hugo 是一个功能强大、速度极快的静态网站生成器，特别适合：

文章数量多的博客（数千篇以上）
需要多语言支持的站点
追求极致生成速度的用户
喜欢 Go 语言生态的开发者

Hugo 的学习曲线比 Hexo 稍陡，但一旦掌握，你会发现它的灵活性和强大功能令人印象深刻。

在下一篇文章中，我们将介绍 VitePress —— 一个由 Vue 驱动的现代化静态网站生成器，特别适合技术文档的编写。

目录

前言