Hugo + FixIt 博客搭建指南

Aria2026-01-16约 5 分钟

警告

本文最后更新于 2026-01-16，文中内容可能已过时。

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

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

环境准备

Hugo

Hugo 是基于 Go 语言的静态网站生成器，能够将 Markdown 转换为 HTML。

下载 Hugo Extended（≥0.156.0）以支持 SCSS 编译并适配 FixIt 主题，并解压至 D:\Hugo\bin。

打开系统属性（Win+R → sysdm.cpl），点击 高级 > 环境变量，在 系统变量 中选择 Path，添加 D:\Hugo\bin，以便系统在任意目录下都能识别并运行 Hugo 命令。

打开终端（Win+R → cmd），运行 hugo version，确认输出包含 extended，以验证是否安装。

Git

Git 是分布式版本控制系统，用于管理博客源码与版本历史。

安装后，桌面右键点击 Open Git Bash Here，运行以下命令，配置用户信息：

Bash
1
2
git config --global user.name "你的用户名"
git config --global user.email "你的邮箱地址"

VS Code（可选）

‌VS Code 是代码编辑器，支持 Markdown 预览、Git 集成和 Hugo 模板高亮。

安装时在 选择附加任务 页面勾选所有选项，方便通过右键菜单快速打开项目。
配置中文界面：打开扩展（Ctrl+Shift+X），安装 Chinese (Simplified) Language Pack。
设置 Git Bash 终端：打开终端（Ctrl+`），点击右上角 + 下拉菜单，选择 Git Bash。

自用扩展推荐
类型	扩展名称
必备	Chinese (Simplified) Language Pack：中文界面支持 Even Better TOML：TOML 语法高亮和检查 Hugo Language and Syntax Support：Hugo 模板语法高亮 Prettier - Code formatter：通用代码格式化
可选	Comment Translate：注释翻译 dir tree generator：生成文件目录树 GitHub Theme：GitHub 风格主题 Open in External App：在外部应用中打开文件 vscode-icons：文件图标主题

Typora（可选）

Typora 是所见即所得的 Markdown 编辑器，专注文章内容写作与排版。

VS Code 中右键文件点击在外部应用中打开 > Typora，实现写作与项目管理分离。

搭建博客

创建站点

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

Bash
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
# 创建一个新的 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

git submodule 用于引入主题仓库，后续可通过 git submodule update --remote 同步更新主题。

项目目录结构如下：

Plaintext
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
Hugo/
├── bin/                  # 可执行脚本或工具（自定义）
└── 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 配置》）。

创建以下文件，进行项目说明：

MarkdownREADME.md
1
2
3
# Hugo + FixIt 博客

基于 Hugo 静态网站生成器和 FixIt 主题搭建的个人博客。

预览站点

运行以下任一命令，启动本地服务器（http://localhost:1313）预览与调试网站效果：

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-->

正文内容

手动摘要： 分隔符前内容作为摘要。
Front Matter：在元信息中单独定义摘要 summary。
自动摘要：截取正文前若干内容作为摘要。

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

Bash
1
cp themes/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 "外链图片")