本文章没有找到对应的语言版本

记录了我在 GitHub Pages 搭建 Hugo 的经历

Tip

请务必先通读全文再进行操作，避免一些不必要的错误。

安装 Hugo

Windows

前往官网下载 Hugo 的exe文件，随便找个位置放，然后把他添加到环境变量中即可。

Linux

先安装 Hugo 的二进制文件，可以在官网上下载，也可以直接使用软件包管理器，考虑到apt更新极为缓慢，建议 Debian 系去官网下载deb包进行安装。

sudo apt install hugo    # Debian 系
yay -S hugo              # Arch 系

安装完成后，执行hugo version会看到类似如下的提示：

❯ hugo version  
hugo v0.164.0-ce2470e7012b5ab5fc4e10ebe4027e9f8d9e00dc+extended linux/amd64 BuildDate=2026-07-06T16:39:30Z VendorInfo=gohugoio

即安装完成。

创建项目

我们使用hugo new site <项目名称>来创建项目，比如：

❯ hugo new site myBlog  
Congratulations! Your new Hugo site was created in /home/kuqilin/myBlog.  
  
Just a few more steps...  
  
1. Change the current directory to /home/kuqilin/myBlog.  
2. Create or install a theme:  
  - Create a new theme with the command "hugo new theme <THEMENAME>"  
  - Install a theme from https://themes.gohugo.io/  
3. Edit hugo.toml, setting the "theme" property to the theme name.  
4. Create new content with the command "hugo new content <SECTIONNAME>/<FILENAME>.<FORMAT>".  
5. Start the embedded web server with the command "hugo server --buildDrafts".  
  
See documentation at https://gohugo.io/.

可以看到成功的提示，接下来cd到项目文件夹myBlog，按照提示进行配置。

创建或安装主题

显然，我们是可以自己创建主题的，但是为了白嫖方便，直接前往 Hugo Themes 下载一个称心的即可，这里选择了 hugo-theme-reimu 这个主题。

主题安装有几种方式，推荐使用 Git Submodule：

cd myBlog
git init
git submodule add https://github.com/D-Sketon/hugo-theme-reimu.git themes/hugo-theme-reimu

也可以直接下载主题压缩包，解压到themes文件夹下。

然后在 hugo.toml 中指定主题：

theme = "hugo-theme-reimu"

配置 hugo-theme-reimu

主题的配置文件默认在 themes/hugo-theme-reimu/config/_default/ 下。我们不应该直接修改主题文件，因为更新主题时会将其覆盖掉，所以应该在项目根目录的 config/_default/ 下创建同名文件来覆盖。我们把params.yml（主题参数）复制即可。

基础站点配置（hugo.toml） 

baseURL = 'https://<你的用户名>.github.io/'
theme = "hugo-theme-reimu"
title = "xxx's Blog"       # 站点标题
locale = "zh-CN"           # 语言
languageName = "简体中文"   # 语言名称
hasCJKLanguage = true      # 是否包含 CJK 字符

[markup.highlight]         # 语法高亮（含代码块必须）
guessSyntax = true
noClasses = false

[markup.goldmark.renderer]
unsafe = true

[markup.goldmark.extensions.passthrough] # 含数学公式必须
enable = true
delimiters.block = [["\\[", "\\]"], ["$$", "$$"]]
delimiters.inline = [["\\(", "\\)"], ["$", "$"]]

unsafe = true 允许在 Markdown 中直接使用 HTML，passthrough 用于支持数学公式的 $...$ 和 $$...$$ 语法。

主题参数配置（params.yml）

在 config/_default/params.yml 中配置主题的各项功能，这里介绍几个关键项：

导航菜单：

menu:
  - name: home
    url: ""
  - name: archives
    url: "archives"
  - name: about
    url: "about"
  - name: friend
    url: "friend"

个人信息和头像：

author: <你的名字>
email: <你的邮箱>
avatar: "avatar.jpg"           # 放在 static/avatar/ 下
banner: "images/banner.webp"   # 放在 static/images/ 下

社交链接：

social:
  email: mailto:<你的邮箱>
  github: https://github.com/<你的用户名>
  twitter: https://twitter.com/<你的用户名>

侧边栏和小组件：

sidebar:
  position: left  # 左右可选
widgets:
  - category
  - tag
  - tagcloud
  - recent_posts

评论区（以 Waline 为例）：

comment:
  default: waline
waline:
  enable: true
  serverURL: "<你的 Waline 服务地址>"

启用功能：

toc: true                # 目录
dark_mode:
  enable: auto           # 自动跟随系统
math:
  mathjax:
    enable: true         # 数学公式
show_update_time: true   # 显示更新时间

更多配置项（鼠标特效、Live2D、字体、加载动画等）请参考主题官方文档。

配置完成后，运行 hugo server -D 即可在本地预览 http://localhost:1313。

其他内容

其他内容，比如更改鼠标指针、修改字体、文章头图、文章封面、网站主题色、短代码、友链等等，请查看官方文档，这里不再赘述。嘻嘻

部署到 GitHub Pages

部署的核心思路是把 Hugo 构建生成的 public/ 目录推送到 <用户名>.github.io 仓库。GitHub Pages 会自动将这个仓库的内容作为静态网站发布。

也就是说，我们需要两个仓库：

  • 源码仓库（如 hugo-build）：放 Hugo 项目源文件（Markdown、配置、主题等）
  • 页面仓库（<用户名>.github.io）：只放 public/ 里的静态文件

下面分别介绍手动推送和 GitHub Actions 自动推送两种方式。

方式一：手动推送到 github.io

最直接的方式——在本地执行 hugo 构建，然后把 public/ 目录的内容推到页面仓库。

1. 克隆页面仓库 

git clone https://github.com/<你的用户名>/<你的用户名>.github.io.git public

如果 public/ 目录已存在（Hugo 构建会生成），先删掉再克隆。

2. 构建并推送 

# 回到源码仓库根目录，先构建
hugo

# 进入 public 目录（此时它已经是页面仓库的克隆）
cd public

# 提交并推送
git add .
git commit -m "update"
git push origin main

每次更新博客时，重复上面几步即可。

3. 写个脚本简化操作

可以把以上步骤写成一个脚本 deploy.sh：

#!/bin/bash
echo "Building..."
hugo

echo "Deploying..."
cd public
git add .
git commit -m "update $(date '+%Y-%m-%d %H:%M:%S')"
git push origin main
cd ..
echo "Done!"

以后只需运行 bash deploy.sh 就完成构建和部署了。

这种方式的优点是不依赖任何第三方 CI 服务，简单直接；缺点是需要手动执行，并且要保证本地 Hugo 环境正常。

方式二：GitHub Actions 自动部署

懒人必备——每次把源码推到 GitHub，剩下的构建和部署全交给 Actions 自动完成。

1. 创建 Personal Access Token

为了让 Actions 能够向页面仓库推送代码，需要一个 Token：

  1. GitHub → Settings → Developer settings → Personal access tokens → Tokens(classic)
  2. 生成新 Token，勾选 repo 和 workflow 权限
  3. 复制生成的 Token（注意：此 Token 只显示一次，务必保存好）

然后在源码仓库的 Settings → Secrets and variables → Actions 中新建一个 Secret，名称为 TOKEN，填入刚才复制的 Token。

2. 编写 Workflow 文件

在源码仓库根目录创建 .github/workflows/hugo.yaml：

name: deploy

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
        - name: Checkout
          uses: actions/checkout@v4
          with:
              fetch-depth: 0
              submodules: true       # 如果主题用 git submodule 安装，需要这行

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

        - name: Build Web
          run: hugo

        - name: Deploy Web
          uses: peaceiris/actions-gh-pages@v4
          with:
              PERSONAL_TOKEN: ${{ secrets.TOKEN }}
              EXTERNAL_REPOSITORY: <你的用户名>/<你的用户名>.github.io
              PUBLISH_BRANCH: main
              PUBLISH_DIR: ./public
              commit_message: auto deploy

各步骤说明：

步骤 作用
actions/checkout@v4 拉取源码，submodules: true 同时拉取主题子模块
peaceiris/actions-hugo@v3 安装 Hugo 环境（extended 版支持 SCSS）
hugo 构建站点，生成 public/ 目录
peaceiris/actions-gh-pages@v4 将 public/ 推送到页面仓库

3. 推送源码触发部署 

git add .
git commit -m "new post"
git push origin main

每次 push 到 main 分支后，GitHub Actions 就会自动运行。可以在源码仓库的 Actions 标签页查看构建进度，绿色 ✅ 即为部署成功，随后访问 https://<你的用户名>.github.io/ 就能看到更新后的博客。

两种方式对比

手动推送 GitHub Actions
操作 本地跑 hugo + 手动 push 只需 git push 源码
依赖 本地需安装 Hugo 无需本地环境
适用场景 临时更新、不方便配 Actions 日常写博客，自动化最省心
复杂度 ⭐ 简单 ⭐⭐ 需配一次 Token 和 yaml

两种方式不冲突，可以同时使用——配好 Actions 后日常自动部署，偶尔需要手动推也完全可以。

至此，Hugo 博客的搭建、配置和部署就全部完成了 🎉

说些什么吧！

waline