AriaNote
AriaNote
Tech Hugo

Hugo FixIt 博客搭建指南

约 5 分钟
/images/20260508_O78fLt.webp
警告
本文最后更新于 2026-01-16，文中内容可能已过时。

搭建 Hugo 博客，本质上是在做三件事：写内容、选外观、让它们组合成可访问的网站。

本文以 FixIt 主题为例，介绍 Hugo 博客的本地搭建过程，Hugo 通过预设结构和配置，自动结合内容与主题，用户只需关注创作与外观选择。1

准备工作

在开始之前，准备以下工具：

  • Hugo Extended（≥0.156.0）：静态网站生成器，Extended 版本支持 SCSS 编译。
  • Git：版本控制，用于管理博客源码与部署。
  • Go（可选）：仅 Hugo Module 方式引入主题时需要。
  • VS Code（可选）：代码编辑器，支持 Markdown 预览与 Git 集成。
  • Typora（可选）：所见即所得的 Markdown 编辑器，适合专注写作。

工具的安装与配置详见《Win11 开发环境安装与配置》。

搭建博客

主题决定博客的外观和功能，引入主题有两种方式：

  • Git Submodule：主题源码放在 themes/ 目录，看得见、改得动，只需 Git，但配置要复制全量副本，主题更新后还得手动同步。
  • Hugo Module：通过 Go 模块管理，版本可锁定，配置只写要覆盖的键，其余自动继承，但主题源码默认不可见，需要 hugo mod vendor 导出到 _vendor/，且必须额外安装 Go。2

两种方式都能正常构建，按需选择即可，后续步骤相同。

运行以下命令，创建 Hugo 项目并添加 FixIt 主题：

Bash
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

# 创建名为 blog 的 Hugo 项目
hugo new site blog

# 进入项目目录
cd blog

# 初始化 Git 仓库
git init

# 添加 Hugo 主题：FixIt
git submodule add https://github.com/hugo-fixit/FixIt.git themes/FixIt
echo "theme = 'FixIt'" >> hugo.toml
echo "defaultContentLanguage = 'zh-cn'" >> hugo.toml

项目目录结构如下：

Plaintext
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

blog/
├── archetypes/       # 内容模板（Front Matter 模板）
├── assets/           # 资源文件（SCSS / JS，经 Hugo Pipes 处理）
├── content/          # 博文内容（Markdown 页面）
├── data/             # 数据文件（YAML / JSON / TOML，可在模板中读取）
├── i18n/             # 多语言翻译文件
├── layouts/          # 页面模板（覆盖或扩展主题模板）
├── static/           # 静态资源（图片、CSS、JS，构建时原样复制）
├── themes/           # 主题目录（FixIt）
├── .gitmodules       # Git 子模块配置（用于引入主题）
└── hugo.toml         # 站点配置文件

修改站点配置文件，添加以下内容以合并默认配置：

TOMLhugo.toml
1
2
3
4
5
6
7
8

ignoreLogs = ['warning-dev-version']

[markup]
  _merge = "shallow"
[outputs]
  _merge = "shallow"
[taxonomies]
  _merge = "shallow"

运行以下命令，将主题配置文件复制到项目目录，避免主题更新时被覆盖：

Bash
1
2

mkdir -p config/_default
cp themes/FixIt/hugo.toml config/_default/

之后修改主题配置只需编辑 config/_default/hugo.toml（详见 FixIt 配置）。

运行以下命令，创建 Hugo 项目并添加 FixIt 主题：

Bash
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

# 创建名为 blog 的 Hugo 项目
hugo new site blog

# 进入项目目录
cd blog

# 初始化 Git 仓库
git init

# 初始化 Hugo Module
hugo mod init github.com/yourname/blog

# 写入基础配置
echo "defaultContentLanguage = 'zh-cn'" >> hugo.toml

主题更新命令：hugo mod get -u（忽略指定版本）。

项目目录结构如下：

Plaintext
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

blog/
├── archetypes/       # 内容模板（Front Matter 模板）
├── assets/           # 资源文件（SCSS / JS，经 Hugo Pipes 处理）
├── content/          # 博文内容（Markdown 页面）
├── data/             # 数据文件（YAML / JSON / TOML，可在模板中读取）
├── i18n/             # 多语言翻译文件
├── layouts/          # 页面模板（覆盖或扩展主题模板）
├── static/           # 静态资源（图片、CSS、JS，构建时原样复制）
├── themes/           # 空目录，Hugo Module 模式下不使用，可删除
├── go.mod            # Hugo Module 依赖声明
├── go.sum            # Hugo Module 依赖校验
└── hugo.toml         # 站点配置文件

修改站点配置文件，添加以下内容以合并默认配置：

TOMLhugo.toml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

ignoreLogs = ['warning-dev-version']

[module]
[[module.imports]]
path = "github.com/hugo-fixit/FixIt"

[markup]
  _merge = "shallow"
[outputs]
  _merge = "shallow"
[taxonomies]
  _merge = "shallow"

运行以下命令，让 Hugo 解析并下载依赖：

Bash
1
2
3
4
5

# 根据配置解析依赖，下载主题
hugo mod tidy

# 将模块依赖复制到 _vendor 目录
hugo mod vendor

主题配置直接写在根目录 hugo.toml 即可，只写要覆盖的键，其余自动继承主题默认值，可打开 _vendor/github.com/hugo-fixit/FixIt/hugo.toml 对照，或参考 FixIt 配置。

预览站点

运行以下任一命令，启动 本地服务器 预览与调试网站效果：

Bash
1
2
3
4
5
6
7
8

# 日常写作：快速预览文章（快速渲染模式）
hugo server -D

# 深度调试：修改主题或样式，确保更改完整生效
hugo server -D --disableFastRender

# 部署检查：模拟线上环境，测试评论、CDN 等功能
hugo server -D -e production --disableFastRender

文章管理

Hugo 博客文章通常存放在 content/posts 目录，普通文章仅包含 Markdown 文件，而 页面束（Page Bundle）是适用于附带资源（如图片、附件）的文件夹结构。

运行以下命令，创建普通文章或页面束：

Bash
1
2
3
4
5

# 创建普通文章
hugo new posts/title.md

# 创建 Page Bundle，适用于含图片或附件的文章
hugo new posts/title/index.md

目录结构示例如下：

Plaintext
1
2
3
4
5
6
7

content/
└── posts/
    ├── normal-article.md      # 普通文章，只包含 Markdown 文件
    └── bundle-article/        # 页面束（Page Bundle）
        ├── index.md           # 文章的 Markdown 文件
        ├── image.jpg          # 文章相关图片
        └── attachment.pdf     # 文章附件

打开文章文件，位于开头的是用于描述元信息的 Front Matter（--- 包裹），示例如下：

Markdown
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

---
title: "{{ replace .Name "-" " " | title }}"
slug: "{{ .File.BaseFileName }}"
date: {{ .Date }}
lastmod: {{ .Date }}
categories: ["分类"]
collections: ["合集"]
summary: "{{ .File.BaseFileName }}"
draft: true
---

<!--more-->

正文内容
  1. 手动摘要：<!--more--> 分隔符前内容作为摘要。
  2. Front Matter：在元信息中单独定义摘要 summary。
  3. 自动摘要：截取正文前若干内容作为摘要。

运行以下命令，将主题内容模板复制到项目目录，避免主题更新时被覆盖：

Bash
1
2
3
4
5

# Git Submodule
cp themes/FixIt/archetypes/posts.md archetypes/

# Hugo Module
cp _vendor/github.com/hugo-fixit/FixIt/archetypes/posts.md archetypes/

之后修改 Front Matter 模板只需编辑 archetypes/posts.md（详见 FixIt Front Matter）。

图片管理

文章图片存储方式如下：

  • 本地存储：存于 assets/、static/，或 Page Bundles，引用相对路径。
  • 图床存储：上传至外部图床，引用绝对路径。

图片在 Markdown 中的引用示例如下：

Markdown
1
2
3
4
5
6

# 本地存储
![页面束图片](pic.png "页面束图片") 
![静态目录图片](/images/pic.png "静态目录图片")

# 图床存储
![外链图片](https://example.com/path/to/pic.jpg "外链图片")

更多自动化图片管理与图床方案，详见《Hugo + PicList 多图床搭建实践》。

后续步骤

🎉 恭喜完成 Hugo 博客本地搭建！接下来部署站点以实现自动构建与在线访问，详见《Hugo 博客自动化部署指南》（GitHub Pages / Cloudflare Pages）。

  1. 快速入门 - Hugo
    快速上手 - FixIt ↩︎

  2. Hugo Modules - Hugo ↩︎

author avatar
张小鱼
温故而知新，可以为师矣
赞赏
张小鱼 支付宝支付宝
本博客部分代码由 AI 辅助生成，内容采用 CC BY-NC-SA 4.0 协议，转载请注明来自 AriaNote
Hugo
2026-01-16
Markdown 写作语法手册
2026-01-16
Hugo Shortcodes 语法手册
2026-01-16
Hugo + PicList 多图床搭建实践
2026-01-16
Hugo 图床迁移：从本地到云端
2026-01-16
Hugo 图床迁移：从云端到本地
2026-01-17
Hugo 博客自动化部署指南
留言交流
更新于 2026-01-16 
CC BY-NC-SA 4.0
返回 | 主页

目录

合集 · Hugo