Hugo + Stack + GitHub Pages 博客搭建指南

Mon, 08 Dec 2025 00:00:00 +0000

Hugo + Stack + GitHub Pages 博客搭建指南

使用 Hugo + Stack 主题搭建个人博客，并部署到 GitHub Pages 的完整流程。

本文兼顾 新版 Stack（v4.x，config 为 .toml 拆分格式） 和 旧版（v3.x，单文件 hugo.yaml） 的配置差异，关键差异处会标注说明。

环境准备

安装 Git

前往 Git 官网下载安装：https://git-scm.com/downloads
全部默认选项安装即可

安装 Hugo（Extended 版本）

前往 Hugo GitHub Releases：https://github.com/gohugoio/hugo/releases
选择 extended 版本（带 extended 字样），Stack 主题需要 extended 版本的 SCSS 编译支持
Windows 用户下载 hugo_extended_xxx_windows-amd64.zip，解压得到 hugo.exe

本文编写时使用的 Hugo 版本为 v0.161.1，Stack 主题版本为 v4.0.2。

GitHub 账号

注册 GitHub 账号：https://github.com
建议开启两步验证（2FA），可在 Edge 安装 Authenticator 2FA Client 插件

创建 Hugo 站点

初始化项目

在 hugo.exe 所在目录打开终端（地址栏输入 cmd 或 powershell），执行：

# 创建新站点
hugo new site myblog

# 进入站点目录
cd myblog

生成的文件结构：

myblog/
├── archetypes/    # 文章模板
├── assets/        # 静态资源（图片、CSS、JS）
├── content/       # 博客内容（文章）
├── data/          # 数据文件
├── i18n/          # 多语言
├── layouts/       # 布局模板
├── public/        # 构建输出（hugo 命令生成）
├── static/        # 静态文件（直接复制到 public）
├── themes/        # 主题
└── hugo.toml      # 站点配置

测试默认站点

`1`	`hugo server -D`

浏览器访问 http://localhost:1313/，此时页面会比较简陋（没有主题），Ctrl + C 停止服务。

配置 Stack 主题

下载主题

前往 Stack 主题 GitHub：https://github.com/CaiJimmy/hugo-theme-stack
下载最新 Release 的压缩包（或直接 Download ZIP）
解压到站点 themes/ 目录下

1
2

myblog/themes/
└── hugo-theme-stack-4.0.2/   # 带版本号的文件夹

配置主题文件 ⚠️ 关键步骤

⚠️ 版本差异注意

这一步是最容易出错的地方。新版 Stack（v4.x）和旧版（v3.x）的文件结构完全不同：

对比项	旧版 Stack（v3.x）	新版 Stack（v4.x）
样例目录名	`exampleSite/`	`demo/`
配置文件	单个 `hugo.yaml`	多个 `.toml` 文件在 `config/_default/`
主题引用	`theme: hugo-theme-stack`	`[[module.imports]]`（Hugo Modules 方式）

新版（v4.x）操作步骤：

Step 1：复制配置文件

# 创建 config/_default 目录
mkdir -p config/_default

# 复制 demo 的所有配置文件
cp themes/hugo-theme-stack-4.0.2/demo/config/_default/*.toml config/_default/

复制后 config/_default/ 内有 6 个配置文件：

文件	作用
`hugo.toml`	基础配置（baseURL、title、分页、永久链接等）
`languages.toml`	多语言配置
`markup.toml`	Markdown 渲染配置（代码高亮、目录等）
`menu.toml`	菜单配置（导航栏、社交链接）
`params.toml`	主题参数（侧边栏、评论、widgets 等）
`related.toml`	相关内容推荐配置

Step 2：修改主题引用方式

打开 config/_default/hugo.toml，找到：

1
2

[[module.imports]]
    path = "github.com/CaiJimmy/hugo-theme-stack/v3"

替换为：

`1`	`theme = "hugo-theme-stack-4.0.2"`

这种传统方式不需要 Go 环境和 Hugo Modules，更简单，和教程保持一致。

Step 3：处理根目录 hugo.toml 冲突

项目根目录的 hugo.toml 和 config/_default/hugo.toml 会冲突，备份或删除根目录的文件：

`1`	`mv hugo.toml hugo.toml.bak`

Step 4：复制示例内容

# 备份原有的 content（如果有内容的话）
mv content content_backup

# 复制 demo 的 content
cp -r themes/hugo-theme-stack-4.0.2/demo/content .

Step 5：复制头像等静态资源

1
2

mkdir -p assets/img
cp themes/hugo-theme-stack-4.0.2/demo/assets/img/avatar.png assets/img/

旧版（v3.x）操作步骤：

进入主题的 exampleSite/ 文件夹
复制 content 文件夹和 hugo.yaml 到站点根目录
删除根目录的 hugo.toml（因为已经有 hugo.yaml 了）
确认 hugo.yaml 中 theme 字段与主题文件夹名一致（建议去掉版本号）

启动验证

`1`	`hugo server -D`

浏览器访问 http://localhost:1313/，此时应该能看到完整的 Stack 主题效果（带侧边栏、搜索、示例文章等）。

如果页面不完整，检查终端是否有 WARN 提示（如 Search page not found、Archives page not found 等），通常是因为没有复制示例 content。

自定义配置

基础信息

编辑 config/_default/hugo.toml（新版）或 hugo.yaml（旧版）：

1
2

baseURL = "https://你的用户名.github.io/"
title   = "我的博客"

如果你以中文为主，建议设置：

1
2

defaultContentLanguage = "zh-cn"
hasCJKLanguage         = true   # 中文/日文/韩文设为 true

侧边栏

编辑 config/_default/params.toml（新版）或 hugo.yaml 的 params.sidebar 部分：

[sidebar]
    emoji    = "✏️"
    subtitle = "你的个性签名"
    avatar   = "img/avatar.png"

将头像图片放到 assets/img/avatar.png
emoji 可以在 emojiall.com 挑选

社交链接

编辑 config/_default/menu.toml（新版）或 hugo.yaml 的 menu.social 部分：

[[social]]
    identifier = "github"
    name       = "GitHub"
    url        = "https://github.com/你的用户名"
    params.icon = "brand-github"

图标名称参考 Tabler Icons（使用 brand-xxx 格式）。

评论系统

Stack 支持多种评论系统，以 utterances 为例（基于 GitHub Issues，无需额外注册）：

[comments]
    enabled  = true
    provider = "utterances"

    [comments.utterances]
        repo      = "你的用户名/你的用户名.github.io"
        issueTerm = "pathname"
        label     = ""

更多评论系统配置参考主题文档：https://stack.jimmycai.com/config/comments

页脚

1
2

[footer]
    since = 2026

创建文章

文章结构

Stack 主题推荐每篇文章用一个文件夹，包含 index.md 和图片资源：

`1`	`hugo new content post/我的第一篇文章/index.md`

生成的目录结构：

1
2
3

content/post/我的第一篇文章/
├── index.md      # 文章内容
└── image.jpg     # 文章配图（可选）

文章 Front Matter 示例

---
title: 我的第一篇文章
date: 2026-05-12
description: 文章摘要描述
tags:
  - Hugo
  - 博客
categories:
  - 教程
image: image.jpg   # 文章封面图（可选）
---

部署到 GitHub Pages

创建 GitHub 仓库

登录 GitHub，点击 New repository
仓库名填写：你的用户名.github.io（必须精确匹配）
选择 Public（GitHub Pages 免费版要求公开）
不勾选 “Add a README file”

手动部署

# 1. 构建静态网站（输出到 public/）
hugo -D

# 2. 进入 public 目录
cd public

# 3. 初始化 Git 并推送
git init
git add .
git commit -m "first commit"
git branch -M main
git remote add origin https://github.com/你的用户名/你的用户名.github.io.git
git push -u origin main

推送成功后，访问 https://你的用户名.github.io/ 即可看到博客（首次可能需要等待 1-2 分钟）。

自动部署（GitHub Actions）

每次手动构建推送很繁琐，可以用 GitHub Actions 实现推送代码 → 自动构建部署。

Step 1：创建源仓库

除了 用户名.github.io 这个部署仓库外，再创建一个源仓库（如 myblog），把整个 Hugo 项目推送到源仓库：

# 在站点根目录（不是在 public/ 里）
git init
git add .
git commit -m "init hugo site"
git branch -M main
git remote add origin https://github.com/你的用户名/myblog.git
git push -u origin main

Step 2：创建 GitHub Actions 工作流

在站点根目录创建 .github/workflows/deploy.yml：

name: Deploy Hugo site to GitHub Pages

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          submodules: true
          fetch-depth: 0

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

      - name: Build
        run: hugo --minify

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v4
        with:
          personal_token: ${{ secrets.PERSONAL_TOKEN }}
          external_repository: 你的用户名/你的用户名.github.io
          publish_branch: main
          publish_dir: ./public

Step 3：配置 GitHub Token

进入 GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)
生成新 Token，勾选 repo 和 workflow 权限
复制生成的 Token
进入源仓库 → Settings → Secrets and variables → Actions → New repository secret
Name 填写 PERSONAL_TOKEN，Value 粘贴 Token

之后每次 git push 到源仓库的 main 分支，GitHub Actions 就会自动构建并部署到 用户名.github.io。

💡 开启 lastmod 自动获取
在 config/_default/hugo.toml（新版）或 hugo.yaml（旧版）中添加：
1
2
3
enableGitInfo = true
[frontmatter]
  lastmod = [":git", ":fileModTime"]
这样文章会自动显示 Git 提交时间作为最后修改时间。这要求在 GitHub Actions 的 checkout 步骤中 fetch-depth: 0（已在上方配置中包含）。

常见问题

Q1：启动后页面空白/不完整？

检查是否复制了 demo 的 content 文件夹。缺少示例页面（search、archives 等）会导致主题显示不完整。

Q2：`hugo server` 报错 “Theme not found”？

新版：检查 config/_default/hugo.toml 中的 theme = "xxx" 是否与 themes/ 下的文件夹名一致
旧版：检查 hugo.yaml 中的 theme 字段

Q3：根目录 `hugo.toml` 和 `config/_default/hugo.toml` 冲突？

删除或备份根目录的 hugo.toml，Hugo 会优先使用 config/_default/ 下的配置文件。

Q4：推送到 GitHub 失败？

可能是网络问题，取消代理试试：

1
2

git config --global --unset http.proxy
git config --global --unset https.proxy

Q5：新版的 `[[module.imports]]` 是什么？

新版 Stack 默认使用 Hugo Modules（Go 模块）方式引入主题，需要 Go 环境。如果不想折腾 Go，直接改用 theme = "主题文件夹名" 的传统方式即可。

Q6：博客部署后样式错乱？

检查 baseURL 是否正确配置为 https://你的用户名.github.io/（注意结尾的 /）。baseURL 错误会导致 CSS/JS 资源加载失败。

GitHub Pages on Yanmu

Hugo + Stack + GitHub Pages 博客搭建指南

Hugo + Stack + GitHub Pages 博客搭建指南

环境准备

安装 Git

安装 Hugo（Extended 版本）

GitHub 账号

创建 Hugo 站点

初始化项目

测试默认站点

配置 Stack 主题

下载主题

配置主题文件 ⚠️ 关键步骤

新版（v4.x）操作步骤：

旧版（v3.x）操作步骤：

启动验证

自定义配置

基础信息

侧边栏

社交链接

评论系统

页脚

创建文章

文章结构

文章 Front Matter 示例

部署到 GitHub Pages

创建 GitHub 仓库

手动部署

自动部署（GitHub Actions）

常见问题

Q1：启动后页面空白/不完整？

Q2：`hugo server` 报错 “Theme not found”？

Q3：根目录 `hugo.toml` 和 `config/_default/hugo.toml` 冲突？

Q4：推送到 GitHub 失败？

Q5：新版的 `[[module.imports]]` 是什么？

Q6：博客部署后样式错乱？

参考资料

GitHub Pages on Yanmu

Hugo + Stack + GitHub Pages 博客搭建指南

Hugo + Stack + GitHub Pages 博客搭建指南

环境准备

安装 Git

安装 Hugo（Extended 版本）

GitHub 账号

创建 Hugo 站点

初始化项目

测试默认站点

配置 Stack 主题

下载主题

配置主题文件 ⚠️ 关键步骤

新版（v4.x）操作步骤：

旧版（v3.x）操作步骤：

启动验证

自定义配置

基础信息

侧边栏

社交链接

评论系统

页脚

创建文章

文章结构

文章 Front Matter 示例

部署到 GitHub Pages

创建 GitHub 仓库

手动部署

自动部署（GitHub Actions）

常见问题

Q1：启动后页面空白/不完整？

Q2：hugo server 报错 “Theme not found”？

Q3：根目录 hugo.toml 和 config/_default/hugo.toml 冲突？

Q4：推送到 GitHub 失败？

Q5：新版的 [[module.imports]] 是什么？

Q6：博客部署后样式错乱？

参考资料

Q2：`hugo server` 报错 “Theme not found”？

Q3：根目录 `hugo.toml` 和 `config/_default/hugo.toml` 冲突？

Q5：新版的 `[[module.imports]]` 是什么？