Hugo主题搭建教程

Tue, 01 Sep 2026 11:36:00 +0800

前言

本文为 Hugo Theme Stack 主题搭建教程（为Windows教程 Mac/Linux系统命令可能有所出入）

前置要求

本地已正确安装 Git、Hugo 环境，并配置好系统环境变量，可在终端正常调用相关指令。

`1`	`hugo version`

`1`	`git version`

1.初始化git

进入博客项目根文件夹，打开终端执行以下命令，初始化本地 Git 仓库（可选：并配置远程仓库地址如GitHub GitLab Gitea等）

`1`	`git init`

`1`	`git remote add origin 远程仓库地址（可选）`

2.初始化hugo

使用hugo 创建hugo站点骨架 –force 意思为强制覆盖（因为git init 使该文件夹不为空所以需要强制覆盖）

`1`	`hugo new site . --force`

3.下载主题

推荐使用 Git 子模块（submodule）安装主题，区别于 git clone：该方式不会把主题代码提交进博客仓库只会在根目录生成轻量标记 .gitmodules 文件：记录主题仓库地址、存放路径；目录记录：只保存当前锁定的主题提交哈希值（相当于记一个版本快照）；你的博客仓库永远干净，只有你自己写的文章、配置，第三方主题代码不入库。后期初始化并拉取子模块主题代码

3.1 添加主题子模块

根据自身网络环境选择对应命令（网络不稳定优先选择 SSH 方式）

1
2

# HTTPS 方式（通用，无需配置SSH密钥）
git submodule add https://github.com/CaiJimmy/hugo-theme-stack/ themes/hugo-theme-stack

1
2

# SSH 方式（网络更稳定，需提前配置GitHub SSH密钥）
git submodule add git@github.com:CaiJimmy/hugo-theme-stack.git themes/hugo-theme-stack

3.2 拉取主题完整源码

初始化并同步子模块，拉取 Stack 主题完整源码至 themes/hugo-theme-stack 目录

`1`	`git submodule update --init --recursive`

3.3 备用方案（网络卡顿适用）

如果拉取速度过慢你也可以从 Stack 主题的 GitHub 页面下载 ZIP 压缩包，解压后将文件夹重命名为 hugo-theme-stack，并手动移动到 themes 文件夹内

4.应用配置主题

Stack 主题自带完整演示案例，直接复制演示配置和示例页面，可大幅减少手动配置成本，快速搭建成型博客

1
2

#复制配置目录
xcopy themes\hugo-theme-stack\demo\config config\ /E /I /Y

1
2

#复制示例页面（如关于、归档页等）
xcopy themes\hugo-theme-stack\demo\content content\ /E /I /Y

5.核心配置文件修改（关键步骤）

这是最关键的一步，我们将 Stack 主题的演示配置应用到你的站点，并修改基础信息

5.1 前置配置

你需要修改或确认以下关键项：

用文本编辑器（如 VS Code）打开 config/_default/hugo.toml。
指定主题：在文件顶部附近添加或找到 theme 行，确保其值为 hugo-theme-stack
Hugo 初始化时可能在根目录生成了一个 hugo.toml 文件，它会和 config/_default/ 目录冲突。请手动删除它

5.2 配置文件参考

# ========================
# 基本站点设置
# ========================

# 站点的基础URL
# 本地预览时设为 "/"，部署到 GitHub Pages 时改为真实域名
# 例如：https://你的用户名.github.io/
baseURL = "/"

# 站点语言环境
# 中文博客建议设为 "zh"，英文博客保持 "en-us"
locale = "zh"

# 站点标题，显示在浏览器标签页和页面头部
title = "我的博客"

# ========================
# 国际化 / 语言设置
# ========================

# 默认内容语言
# 与 locale 保持一致，中文设为 "zh"
defaultContentLanguage = "zh"

# 是否包含 CJK（中日韩）语言
# 写中文博客务必设为 true
# 否则 .WordCount（字数统计）和 .ReadingTime（阅读时间）会按英文单词计算，结果严重不准
hasCJKLanguage = true

# ========================
# 主题设置
# ========================

# 指定主题文件夹名称（对应 themes/ 目录下的文件夹名）
# 如果你用 git clone 安装到了 themes/hugo-theme-stack，这里填 "hugo-theme-stack"
# 注意：使用 theme 字段后，应删除 [[module.imports]] 段落，避免冲突
theme = "hugo-theme-stack"

# ========================
# 分页设置
# ========================

[pagination]
    # 每页显示的文章数量
    # 首页、分类页、标签页等列表页面每页展示的文章数
    # 建议 5~10，太少了翻页频繁，太多了加载慢
    pagerSize = 5

# ========================
# 永久链接格式
# ========================

[permalinks]
    # 文章（post）的URL格式
    # /:slug/ 表示使用文章的 slug（即文件夹名或手动指定的别名）作为路径
    # 例如 content/post/hello-world/index.md → /p/hello-world/
    # 你可以改成其他格式，如 /:year/:month/:slug/ 或 /:sections/:slug/
    post = "/:slug/"

    # 固定页面（page）的URL格式
    # 例如 content/page/about.md → /about/
    page = "/:slug/"

# ========================
# 评论系统（可选）
# ========================

# Disqus 评论系统配置
# 如果不需要评论功能，可以注释掉或删除整个 [services.disqus] 段落
# 也可以替换为其他评论系统（如 Twikoo、Waline 等国内友好的方案）
#[services.disqus]
    # 你在 Disqus 上注册的站点 shortname
    # 不需要评论时注释掉此行即可
    #shortname = ""

6.本地启动博客预览

配置完成后，执行启动命令，运行本地开发服务：

1
2

# 启动本地预览服务，渲染草稿文章
hugo server -D

启动成功后，打开浏览器访问 http://localhost:1313，即可看到完整的 Stack 主题博客页面。

好了剩下的时间就留给各位自行探索了

杂项 on css的小站