Hugo 搭建教程

什么是 Hugo

Hugo 是由 Go 语言编写的快速现代静态网站生成器，旨在让网站创建变得有趣。

Hugo 是一个通用的网站框架。从技术角度来说，Hugo 是一个静态网站生成器。与每个访问者请求动态构建页面的系统不同，Hugo 在创建或更新内容时构建页面。由于网站被查看的频率远远多于编辑的频率，Hugo 旨在为您的网站最终用户提供最佳的查看体验，并为网站作者提供理想的编写体验。

Hugo 的特点

  • 快速: Hugo 可以在毫秒级别构建网站
  • 安全: 静态网站天然具有更高的安全性
  • 无需数据库: 不需要数据库或 Ruby、Python、PHP 等昂贵运行时的依赖
  • 灵活托管: Hugo 网站可以托管在任何地方，包括：

一、Hugo 下载与安装

1. 官方资源

2. 包管理器安装（推荐）

以下三种方式任选其一即可：

方式 1：Chocolatey

Chocolatey 是 Windows 上的一个免费且开源的包管理器。

1
choco install hugo-extended

方式 2：Scoop

Scoop 是 Windows 上的一个免费且开源的包管理器。

1
scoop install hugo-extended

方式 3：Winget（推荐）

Winget 是 Microsoft 的官方免费且开源的 Windows 包管理器。

1
winget install Hugo.Hugo.Extended

提示: 建议安装 hugo-extended（扩展版），支持 SCSS/SASS 等功能。

3. 验证安装

安装完成后，使用以下命令验证是否安装成功：

1
hugo version

二、创建新站点

1. 创建站点

在命令行中进入你想要创建站点的目录，然后执行：

1
hugo new site blog

这会在当前目录创建一个名为 blog 的文件夹，包含以下基本结构：

1
2
3
4
5
6
7
8
9
10
blog/
├── archetypes/
├── assets/
├── content/
├── data/
├── layouts/
├── static/
├── themes/
├── hugo.toml
└── hugo_stats.json

2. 启动本地服务器

进入刚创建的站点目录并启动服务器：

1
2
cd blog
hugo server

默认情况下，Hugo 会在 http://localhost:1313 启动本地服务器。在浏览器中打开该地址即可查看站点。

三、安装主题

1. 选择主题

这里推荐使用 hugo-theme-reimu 主题：

2. 安装主题

方式 1：Hugo Module（推荐）

适用于熟悉 Go 生态的用户，支持版本管理和自动更新。

1
2
3
hugo mod init github.com/<your-github-username>/quickstart
echo 'theme = ["github.com/D-Sketon/hugo-theme-reimu"]' >> hugo.toml
hugo server

记得将 <your-github-username> 替换为你的 GitHub 用户名。

方式 2：Git Submodule

适用于希望手动管理主题版本的用户。

1
2
3
4
git init
git submodule add https://github.com/D-Sketon/hugo-theme-reimu.git themes/reimu
echo 'theme = "reimu"' >> hugo.toml
hugo server

3. 配置主题

主要配置文件位置

配置文件 位置 说明
网站配置 hugo.toml 网站基本信息配置
主题配置 themes/reimu/config/_default/params.yml 主题参数配置
封面配置 data/covers.yml 文章封面图配置
头像图片 static/avatar/avatar.webp 个人头像
文章内容 content/post/ 博客文章存放目录

修改个人信息

在配置文件中修改以下信息：

1
2
3
# 网站基本信息
title: 夙夜凌风
email: suyelingfeng666@outlook.com

四、创建归档页面

1. 创建归档页面文件

Hugo 需要一个 _index.md 文件来定义归档页面。在 content/archives/ 目录下创建 _index.md 文件：

1
2
3
4
---
title: 归档
layout: archives
---

2. 归档页面功能

创建归档页面后，Hugo 会自动：

  • 显示所有文章，按年份/月份分组
  • 显示每篇文章的标题、日期、分类和标签
  • 显示文章的封面缩略图（如果有）
  • 使用主题的归档布局

访问 http://localhost:1313/archives 即可查看归档页面。

五、配置评论系统

方案 1：使用博客仓库

如果博客已经托管在 GitHub 上，可以直接使用博客仓库。

假设你的博客仓库是 xiaoluo/hugo-blog，配置如下：

1
2
3
4
5
utterances:
  enable: true
  repo: xiaoluo/hugo-blog
  issue_term: title
  theme: auto

方案 2：创建独立的评论仓库

如果想在独立仓库存储评论：

步骤 1：创建仓库

  1. 访问 https://github.com/new
  2. 仓库名：blog-comments
  3. 设置为 Public
  4. 点击创建

步骤 2：安装 Utterances

  1. 访问 https://github.com/apps/utterances
  2. 点击 “Install”
  3. 选择刚创建的仓库

步骤 3：更新配置文件

假设你的 GitHub 用户名是 xiaoluo，配置如下：

1
2
3
4
5
utterances:
  enable: true
  repo: xiaoluo/blog-comments
  issue_term: title
  theme: auto

临时解决方案（禁用 Utterances）

如果暂时不想配置评论系统，可以先禁用它：

在 params.yml 中设置：

1
2
utterances:
  enable: false

注意事项

本地开发时的问题：

Utterances 评论系统依赖 GitHub API，而 GitHub API 的安全策略不允许从 localhost 等本地地址访问。这是正常的安全限制。

解决方法：

  • 在本地开发时禁用 Utterances
  • 当博客部署到公网域名（如 GitHub Pages、Vercel 等）后，再启用 Utterances

GitHub 仓库设置检查：

  1. 确保仓库是 Public（公开）
  2. 确保 Issues 功能已启用
  3. 已安装 Utterances App

六、部署到 GitHub Pages

第一步：修改 baseURL 配置

确保 hugo.toml 中的 baseURL 已修改为你的 GitHub Pages 地址：

1
baseURL = 'https://username.github.io/'

将 username 替换为你的 GitHub 用户名。

第二步：生成静态文件

在博客根目录执行：

1
hugo

这会在当前目录生成 public 文件夹，包含所有静态网站文件。

第三步：初始化 Git

进入 public 目录并初始化 Git：

1
2
cd public
git init

第四步：关联远程仓库

使用 HTTPS 方式：

1
git remote add origin https://github.com/username/username.github.io.git

使用 SSH 方式：

1
git remote add origin git@github.com:username/username.github.io.git

第五步：添加文件到暂存区

1
git add .

第六步：提交文件

1
git commit -m "首次提交：部署我的 Hugo 博客"

第七步：重命名分支为 main

1
git branch -M main

第八步：推送到 GitHub

1
git push -u origin main

一键执行命令

如果想把所有命令一次性执行：

1
2
3
4
5
6
7
8
9
cd blog && \
hugo && \
cd public && \
git init && \
git remote add origin https://github.com/username/username.github.io.git && \
git add . && \
git commit -m "首次提交：部署我的 Hugo 博客" && \
git branch -M main && \
git push -u origin main

后续更新

只需在博客根目录执行 hugo 生成新文件，然后进入 public 目录执行：

1
2
3
4
cd public
git add .
git commit -m "更新博客"
git push

注意事项

部署方式 说明
HTTPS 方式 推送时需要输入 GitHub 用户名和 Personal Access Token（不是密码）
SSH 方式 需要先在 GitHub 添加你的 SSH 公钥

七、常见问题

1. 找不到归档页面

问题: 访问 /archives 页面显示 404

解决: 确保 content/archives/_index.md 文件存在，并包含正确的 front matter

2. Utterances 评论无法加载

问题: 评论区不显示或报错

解决:

  • 检查仓库是否为 Public
  • 确保 Issues 功能已开启
  • 验证 Utterances App 已安装
  • 本地开发时可能无法显示，部署到公网后才会正常工作

3. 图片不显示

问题: 本地图片上传后不显示

解决:

  • 确保图片放在 static 目录下
  • 图片路径不需要包含 /static，直接使用 /图片名
  • 检查文件名大小写是否正确

八、总结

Hugo 是一个快速、简单、安全的静态网站生成器，非常适合搭建个人博客、文档站点等。通过本教程，你应该能够：

  • ✅ 安装和配置 Hugo
  • ✅ 创建和运行本地站点
  • ✅ 安装和配置主题
  • ✅ 创建归档页面
  • ✅ 配置评论系统
  • ✅ 部署到 GitHub Pages

下一步学习

  1. 深入学习 Hugo 的 Shortcodes（短代码）
  2. 掌握 Hugo 的模板语法
  3. 了解如何自定义主题
  4. 学习 Hugo 的数据处理功能

相关资源