使用 Hugo 在 Github Pages 搭建博客

前言

#

本文为记录我的第一个博客网站的搭建。动机嘛……大概只是想有一个地方来写一点东西，虽然之前有用Notion记录笔记，但那只是考虑给我自己回顾当工具书用。我希望可以用这个博客来写一些经过细致整理过的东西，希望可以坚持下来……

使用到的工具

#

1. 一个 Github 账号
2. 文本编辑器
3. git 软件
4. Github Pages Repositories (后文创建)
5. Hugo (后文安装)

环境、依赖与托管

#

创建 Github Pages

#

Github Pages 是一个静态站点托管服务，它直接从 Github 上的仓库获取文件，构建过程运行文件，然后发布网站，任何人可以通过 Github 的域名访问你的网站。

1. 访问 Github，登录/创建你的帐户
2. 点击右上角 + （create new）-> New repository
3. 将名字设置为 <userName>.github.io 其中 userName 为你的 Github 账户名
4. 将项目设置为 Public
5. 打开 Add README 开关，在创建后自动生成 README 文件
6. 点击 Create repository 创建项目

本地安装 Hugo

#

1. 访问 Hugo 的 Github 仓库，在 release 中下载符合电脑的版本。下载完成后解压。

2. 添加 hugo.exe 所在的路径到系统的环境变量中。(方便我们直接在命令行调用 Hugo)

3. 在命令行中输入命令验证是否安装成功。

hugo version

如果输出版本信息，则代表安装成功

(base) PS C:\Users\CC> hugo version
hugo v0.152.2-6abdacad3f3fe944ea42177844469139e81feda6 windows/amd64 BuildDate=2025-10-24T15:31:49Z VendorInfo=gohugoio

生成网站

#

使用 Hugo 命令生成一个网站模板，之后我们的网站就在这个目录中配置与编写。

hugo new site <your-site-name>

# 例如
hugo new site DoOoOoGes_Blog

可以看到在当前目录下生成了一个新的目录，目录名就是你刚刚的网站名。

进入刚刚生成的目录，可以看到下面的目录结构

<your-site-name>(dir)
│  hugo.toml        # 站点配置文件，后文要用
│
├─archetypes        # 存放文章的模板文件
│      default.md
│
├─assets            # 存放静态资源文件
├─content           # 存放文章的目录
├─data              # 存放数据文件的目录
├─i18n              # 存放国际化文件的目录
├─layouts           # 存放布局文件的目录
├─static            # 存放静态文件的目录
└─themes            # 存放主题的目录

在这个目录下运行以下命令新建一篇文章

hugo new posts/my-first-post.md
# 输出
Content "C:\\Softwares\\HugoBlog\\DoOoOoGes_Blog\\content\\posts\\my-first-post.md" created

此时会在站点目录下的 content 文件夹中生成 posts 文件夹，同时生成你的文章文件 my-first-post.md ，可以使用文本编辑器打开这个文件。

当前 content 目录下的结构

./content
└─posts
        my-first-post.md

打开这个文件可以看到以下的内容

+++
date = '2025-11-24T23:50:37+08:00'
draft = true
title = 'My First Post'
+++

安装 Blowfish 主题

#

可以前往 Blowfist 的 Demo 网站查看主题的效果

1. 拉取主题文件 返回我们创建的网站的目录，使用以下的命令，拉取主题文件

git init -b main

git submodule add -b main https://github.com/nunocoracao/blowfish.git themes/blowfish

第二段命令的意思是，添加一个子模块，子模块可以是一个git管理的项目，位置在 theme/blowfish ，拉取仓库的代码。

2. 替换默认语言 拉取完成后，将 ./themes/blowfish/archetypes 替换 ./archetypes，复制 ./themes/blowfish/config，到 项目的根目录

<your-site-name>(dir)
├─ archetypes   # 复制到这儿
├─ assets
├─ config   # 和这儿
├─ content
├─ data
├─ i18n
├─ layouts
├─ public
├─ static
└─ themes
    └─ blowfish
        ├─ .github
        ...
        ├─ archetypes   # 将这个文件夹
        ...
        ├─ config   # 和这个文件夹
        ...

进入刚刚复制的 config/_default 文件夹，将 languages.en.toml menus.en.toml 中的 en 换为你的语言，如 languages.zh-cn.toml menus.zh-cn.toml

3. 更改配置文件 在 config/_default 文件夹中找到 hugo.toml 文件，

   1. 取消第5、6行的注释

   2. 在开头位置加入这一句 hasCJKLanguage = true

   3. 将 your_domain.com 替换为你的域名，如果没有域名，可以替换为 Github Pages 的名字 https://<userName>.github.io

   4. 将 en 替换为你的默认语言，例如 zh-cn 表示简体中文

改好的文件内容如下：

# -- Site Configuration --
# Refer to the theme docs for more details about each of these parameters.
# https://blowfish.page/docs/getting-started/

theme = "blowfish" # UNCOMMENT THIS LINE
baseURL = "https://DoOoOoGe.github.io"
defaultContentLanguage = "zh-cn"

hasCJKLanguage = true

# pluralizeListTitles = "true" # hugo function useful for non-english languages, find out more in  https://gohugo.io/getting-started/configuration/#pluralizelisttitles

4. 测试 回到根目录，使用以下命令启动本地服务器

hugo server

在浏览器中访问 http://localhost:1313 如果有网页，表示站点界面已经配置成功。

回到终端，按 Ctrl+C关闭服务器。

配置站点

#

定制主要全局信息

#

打开 config/_default/hugo.toml 配置文件。

示例配置

[params]
  displayName = "zh-cn"             # 当前语言在页面上显示的名称
  isoCode = "cn"                    # 当前语言的国际代码
  dataFormat = "2006 年 1 月 2 日"   # 时间格式
  # logo = 

  [params.author]                   # 作者信息
  name = "DoOoOoGe"                 # 名字
  # image =                         # 头像
  # email =
  # headline =                      # 座佑名
  links = [                         # 账号链接
    { github = "https://github.com/DoOoOoGe" },
    { bilibili = "https://space.bilibili.com/109388499" },
  ]

此时打开网页会发现只有 Github 的图标，没有哔哩哔哩的图标，是因为 Github 的图标已经在 Blowfish 的图标库中，我们可以不添加而直接引用这个图标。

如果我们想要显示哔哩哔哩的图标，需要在 asserts/icons 中导入 bilibili.svg。

定制菜单栏

#

打开文件 config/_default/menus.zh-cn.toml。 这里只定制上菜单，完整文档可以参考官方文档

[[main]]
  pre = "blogger"       # 引用 Blowfish 图标库的图标
  name = "Blog"         # 显示的文字
  pageRef = "blogs"     # 链接的内部页面，根页面使用 /
  # url = 链接的外部页面
  weight = 10           # 权重 从左往右权重从小到大

上面的格式是一个菜单栏项，你可以根据上面的格式创建多个菜单栏项。

需要引用 Blowfish 图标，可以参考 Blowfish 图标库 。

配置主题参数

#

打开 config/_default/params.toml 可以按照 官方教程，本部分可以开着浏览器，实时查看修改效果。

这个文件可以配置的页面内容有：

• 全局主题
• 全局控件、按钮显示
• 全局图片大小
• header 上菜单
• footer 下菜单
• 主页
• 文章页
• 列表页
• 站点地图页
• 外部服务（如点击量统计、评论、赞助）

创建文章

#

本章节将说明创建文章的步骤与相关的配置，只是大致了解过程。关于某个方向（如： 短代码 、 头信息 等）会在下文详细说明，如果本文没有说明，也可以查询 官方文档

创建一个文章的命令在上文已经介绍过了：

hugo new posts/my-first-post.md

但是这个文章的头信息可能会和我们之后的样式有点不同。

1. 推荐删除已经创建的文章，重新运行上面的命令 。

2. 打开新创建的文章，可以看到默认的头信息：

---
title: "My First Post"
date: 2025-11-26T21:33:39+08:00
draft: true
description: ""
---

3. 可以在这里修改文章的标题与内容，保存文件

4. 运行命令 hugo server -D

5. 访问地址 http://localhost:1313 ,可以在 Posts 栏目中看到你的文章。

内容目录结构

#

content 目录是一个重要的顶层目录，你可以在 content 目录下创建任意深度的目录。

但是这些深层目录是有不同的，我们可以用一个实验来证明：

看看现在的 content 目录中是不是有一个 posts 目录。目录中是你刚刚创建的一个 Markdown 文件，你可以尝试创建一个新的文件夹（可以取名为 coding ）把 Markdown 文件放入这个目录中。 运行你的网页，点开你的文章，你会发现这个目录不会在文章所在路径中显示出来。

为什么 posts 目录就会被显示，而 coding 目录不会？这里涉及了一个 Hugo 的 章节 知识，不会在这个文章中展开；你需要知道的就是通常的文章目录结构是这样的

content
└── posts
    ├── _index.md
    ├── logo.png
    ├── my-first-post
    │   ├── index.md
    │   └── test-coding.md
    └── my-second-post
        └── index.md

• _index.md 是 posts 章节 的内容文件（index.md 是一个章节的标志），这个 Markdown 文件的内容会展示在 /Posts 路径的页面下。
• logo.png 是 posts 章节 下的内容，可以在 _index.md 中使用。
• my-first-post 是一个 文章捆绑包 ，整个包被看成是一个文章（上面实验中的 coding 目录就是一个文章捆绑包）；其中， index.md 是文章的主要内容；包内可以有多个 Markdown 文件，也可以放图片和其他资源

因此，下次你创建文章的时候，可以连带捆绑包一起创建：

hugo new posts/<your-artical-name>/index.md

需要添加缩略图的文章

#

如果要在文章页面中可以看到缩略图与背景，需要启用 params.toml 中的以下内容

showHero = true
heroStyle = "thumbAndBackground" # valid options: basic, big, background, thumbAndBackground

如果一篇文章需要添加缩略图和背景，需要把 content 目录的结构更改为以下

content
└─posts
    └─my-first-post        # 文章的名字
            feature.png    # 缩略图
            background.png # 文章背景
            index.md       # 文章主体

生成与推送

#

第一次生成与推送

#

万事具备，我们有了一个网站架构、一个样式、一篇文章。现在我们要根据这些内容创建一个静态网页，这样我们可以推送到 Github Pages

1. 在站点根目录下，使用以下的命令生成一个静态网页文件：

# 如果你想在网站上显示草稿文章（目前你的文章都是草稿状态
hugo build -D

# 在正常生产环境的时候使用
hugo

2. 静态的文件都会生成在目录 public 中，所以我们要进入 public 目录中，然后使用以下命令将文件推送到你的 Github 仓库中：

   1. 在 public 目录下创建一个 Git 仓库：

   git init -b main
   

   2. 把 Github Pages 的仓库设置为远程仓库

   git remote add origin https://github.com/<your-github-name>/<your-github-name>.github.io.git
   

   3. 如果你在 Windows 下操作，配置 git 使用它把换行符强制转为 LF

   git config --global core.autocrlf false
   

   4. 拉取远程仓库的更新，并在本地仓库变基

   git pull --rebase origin main
   

   5. 添加所有文件到暂存区

   git add .
   

   6. 提交

   git commit -m "<commit-message>"
   

   7. 推送到远程仓库，并绑定默认推送分支

   git push -u origin main
   

3. 等一段时间， Github Pages 会自动部署，你可以在你的 Github Pages 仓库的 Action 页面查看进度。

你可以访问你的站点：<your-github-name>.github.io

之后的生成与推送

#

有了第一次的基础后，你之后的工作流程可以是下面：

# 在你的博客项目根目录中
hugo
cd ./public
git add .
git commit -m "<commit-message>"
git pull --rebase origin main
git push

结语

#

本文利用了 Github Pages 服务，托管了一个静态的博客网站。网站的构建使用了 Hugo ，样式使用了 Blowfish。

Hugo 是一个可自定义程度非常高的网站框架。

当你真正开始写文章的时候，你可能会发现自己的博客与其他人用同样框架搭建的博客不太一样，有一些功能 Hugo 提供了，但是不知道如何去使用，什么短代码（简码）、标签、选集、评论……这些你知道有，但是就是不知道怎么用的功能，只能死啃文档。

当然， Hugo 与 Blowfish 的这个解决方案使用的人也很多，可以在网上找到很多教程。在这里，感谢各位博主无私地分享自己的经验。

如果你想继续了解，可以查看后面的 Hugo 博客进阶（未完成）。也许会包括以下的拓展内容。

• GitHub Actions 自动构建与推送
• Hugo 常用命令
• Hugo 短代码
• Hugo 头信息
• 标签
• 选集
• 标签列表页
• 标签选集页

参考资料

#

• 褐瞳さん@瞳のBlog - 如何使用Github Page 搭建自己的博客

• Ji Binquan@青萍之声 - 博客搭建记录

• Blowfish 官方配置教程

• Blowfish 菜单配置教程

• Hugo 官方中文文档（可能过时！）

• Hugo 官方原文文档