搭建个人博客——Hugo+Stack4.0主题配置

Thu, 15 Oct 2026 19:23:33 +0800

零基础搭建个人博客——Hugo + Stack 4.0 本地环境完整指南

第一步：安装 Git

Windows安装：打开 git-scm.com/downloads ，点击 Git for Windows/x64 Setup

下载完成后双击安装，安装过程中有几个选项需要注意：

Select Components：保持默认，不用改
Choosing the default editor：建议改选 Use Visual Studio Code as Git’s default editor（如果你已经装了 VS Code）
Adjusting the PATH environment：选第二项 Git from the command line and also from 3rd-party software（默认就是这个）
其余步骤全部默认，一路 Next 到底

安装完成后，打开命令提示符（按 Win + R，输入 cmd，回车），输入：

`1`	`git --version`

看到类似 git version 2.47.0 的输出说明安装成功。

第二步：安装 Hugo Extended 版

Hugo 有两个版本：普通版和 Extended 版。Stack 主题用到了 SCSS 编译，安装 Extended 版,否则后面会报错。这里我们使用0.167.0 Extended 版搭建环境。
Windows安装：打开 Hugo Releases 页面，找到 v0.167.0版本（默认看到的是最新版本，往下拉很好找），在 Assets 里找到文件名包含 extended 和 windows-amd64 的 ZIP 文件，

下载并解压，里面有一个 hugo.exe 文件，接下来把 hugo.exe 放到一个固定位置，然后添加到系统路径，这样在任何目录都能运行 Hugo 命令。

推荐做法：

在 D 盘根目录新建文件夹（或在其它可用分区新建文件夹）
把 hugo.exe 复制进去
打开系统环境变量：按 Win + S 搜索「编辑系统环境变量」，点击「环境变量」，或者鼠标右键点「此电脑」 - 「属性」 - 「高级系统设置」 - 「环境变量」
在「系统变量」里找到 Path，双击
点击「新建」，输入 D:\Hugo
一路确定，关闭所有窗口

打开一个新的命令提示符窗口（已打开的窗口不会读取新的环境变量），输入：

`1`	`hugo version`

看到输出里包含 extended 字样说明安装正确，例如：

`1`	`hugo v0.167.0+extended windows/amd64`

第三步：确认环境正常

两个工具都装好后，在命令提示符（Windows）或终端（Mac）分别运行：

1
2

git --version
hugo version

两条命令都有正常输出，说明环境准备好了。如果任何一条命令提示「不是内部或外部命令」，说明安装没成功，回到对应步骤重新检查。

第四步：创建 Hugo 站点

选一个你想存放博客文件的位置。建议放在容易找到的地方，比如 D:\blog 或 ~/Documents/blog。
在命令提示符里输入（把路径换成你想要的位置，使用命令创建或资源管理器中直接创建均可）：

# Windows 示例，先切换到 D 盘，
d:
mkdir blog
cd blog
# 创建 Hugo 站点，myblog 是文件夹名，可以自己改
hugo new site myblog
cd myblog

创建成功后，myblog 文件夹里会有这些内容：

myblog/
├── archetypes/     ← 文章模板，暂时不用管
├── assets/         ← 自定义样式、脚本放这里（后面会用到）
├── content/        ← 你写的所有文章都放这里
├── layouts/        ← 自定义模板放这里（中级阶段会用到）
├── static/         ← 图片等静态文件放这里
├── themes/         ← 主题放这里，下一步就是往这里放 Stack
└── hugo.toml       ← 站点配置文件，核心配置都在这里

现在最重要的三个文件夹是：content（放文章）、themes（放主题）、config（放配置，下一步会用到，后会创建）。

第五步：安装 Stack 4.0 主题

确保你现在在 myblog 文件夹里，运行：

`1`	`git clone https://github.com/CaiJimmy/hugo-theme-stack/ themes/hugo-theme-stack`

这条命令会把 Stack 主题下载到 themes/hugo-theme-stack 文件夹里。网络不好的话可能需要等几分钟，或者开启科学上网工具。
下载完成后，确认文件夹存在：

1
2

# Windows
dir themes/hugo-theme-stack

能看到一堆文件和文件夹说明下载成功。

ZIP 下载方式（备选）如果 git clone 网络太慢，可以去 github.com/CaiJimmy/hugo-theme-stack 点击绿色的 Code 按钮，选 Download ZIP，解压后把文件夹重命名为 hugo-theme-stack，放到 themes/ 下面即可。
加载主题：打开新建站点根目录下的 hugo.toml 文件添加刚刚下载的模板

baseURL = 'https://example.org/'
locale = 'en-us'
title = 'My New Hugo Project'
theme = 'hugo-theme-stack'   ← 加载模板，模板名称就是文件夹名称「hugo-theme-stack」

启动本地服务WEB服务：

1
2

1、启动Web服务：hugo server -D
2、打开本地网站：http://localhost:1313/

如果看到了下面这个页面，说明 Stack 模板安装成功了。

第六步：复制 demo 配置

Stack 4.0 主题自带了一个演示站点（demo 文件夹），里面包含了完整的配置文件和示例页面。直接复制过来用，比从零开始配置省去大量时间。
复制配置文件夹

1
2

# Windows（在 myblog 目录里运行）
xcopy themes\hugo-theme-stack\demo\config config\ /E /I /Y

复制完成后，myblog 下会出现 config/_default/ 文件夹，里面有这几个文件：

config/_default/
├── hugo.toml       ← 主配置文件：标题、语言、baseURL 等
├── languages.toml  ← 语言设置
├── markup.toml     ← Markdown 渲染设置
├── menu.toml       ← 导航菜单设置
├── params.toml     ← Stack 主题专属参数
└── related.toml    ← 相关文章推荐设置

复制示例页面

1
2

# Windows
xcopy themes\hugo-theme-stack\demo\content\page content\page\ /E /I /Y

这一步复制过来的是归档、搜索等固定页面，Stack 主题的导航栏依赖这些页面。
删除默认配置文件
Hugo 创建站点时自动生成了一个 hugo.toml [ 位置：myblog/hugo.toml ]，现在已经由 config/_default/ 目录接管，需要删掉这个文件避免冲突：

1
2

# Windows
del hugo.toml

第七步：修改基础配置

用文本编辑器打开 config/_default/hugo.toml（推荐 VS Code）。

第一：删除 Hugo Module 加载段

找到以下这几行，整段删掉：

1
2

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

这段是用 Hugo Module 方式加载主题的配置，但我们用的是 git clone 方式，保留这段会导致运行报错。

第二：新增主题指定

在文件顶部（title 那行附近）加上这一行，告诉 Hugo 去 themes 文件夹找主题：

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

第三：修改以下五项配置

# 本地预览时用 "/"，部署到 Cloudflare 后再改成真实域名
baseURL = "/"

# 本地化格式（日期、数字显示方式），中文改成 zh
locale = "zh"

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

# 语言设置，中文改成 zh
defaultContentLanguage = "zh"

# 中文博客必须设置为 true，否则阅读时长计算不准确
hasCJKLanguage = true

第八步：编辑「关于我」页面

demo 已经自带了 about 页面，第六步复制时已经带过来了，直接用编辑器打开：

`1`	`content/page/about/index.zh.md`

第一处：把标题和描述改成你自己的

---
title: 关于
description: 关于本站及其作者的一切。
date: 2026-01-26
lastmod: 2026-01-26
menu:
    main:
        weight: -90
        params:
            icon: user
---

title 和 description 按你的实际情况修改，其余字段保持不动。

第二处：在 Front Matter 下方写你的自我介绍

你好，我是 [你的名字]。

这里写你想让读者知道的内容，比如你在做什么、这个博客写什么方向、怎么联系你。

几句话就够了，不用写太长。

确认固定页面已到位
前面复制 demo 时已经带过来了归档和搜索页面，确认一下：

1
2

# Windows
dir content/page

能看到 about、archives、search 这几个文件夹说明一切正常。

第九步：本地预览

启动本地服务器：

`1`	`hugo server -D`

-D 参数表示同时显示草稿文章，方便本地预览。
看到类似这样的输出说明启动成功：

1
2

Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
Press Ctrl+C to stop

打开浏览器，访问 http://localhost:1313，你的博客首页就出现了。

发布博客——GitHub + Cloudflare Pages 部署完整指南

第一步：注册 GitHub 账号并创建仓库

GitHub 是存放博客代码的地方，Cloudflare Pages 会从这里拉取代码进行构建。
我想大家应该都有Github账号吧，没有就自己注册一个，然后创建仓库

点击 Create repository，仓库创建成功后页面会显示一串命令，先留着，下一步会用到。

第二步：处理主题的 .git 文件夹

这是推送前必须处理的一个问题，跳过这步会导致Git提交时报错。
问题原因: 第一篇用git clone安装 Stack 主题时，主题文件夹里自带了一个 .git 文件夹。使用Git命令初始化时会提示仓库已存在。
解决方法：删除主题里的 .git 文件夹。
打开文件管理器，进入：

`1`	`myblog/themes/hugo-theme-stack/`

找到里面的.git文件夹，直接删除。

注意 .git 是隐藏文件夹，默认可能看不到。

Windows：在文件管理器顶部菜单点「查看」，勾选「隐藏的项目」

删除后主题文件夹里就没有.git了，主题文件会作为普通文件正常推送到 GitHub。

第三步：将本地站点推送到 GitHub并备份到自己的群辉Nas

群晖 NAS 创建 Git 裸仓库（先做！）

PC 终端 SSH 登录群晖：

`1`	`ssh admin@192.168.. -p 122(1222是群辉的SSh端口）`

输入密码登录群晖 shell
进入 git 共享目录，创建裸仓库hugo-blog.git（裸仓库后缀习惯加.git）

# 注意：volume1按你群晖实际存储卷修改，绝大多数是volume1
cd /volume1/git
mkdir hugo-blog.git
cd hugo-blog.git
git init --bare
# 裸仓库创建完成，不要在里面修改任何文件！

退出群晖 ssh

exit

群晖远程仓库地址：admin@192.168.*.*:./volume1/git/hugo-blog.git

本地初始化 Hugo 站点 myblog

在命令提示符里，确保你在 myblog 目录下，依次运行以下命令：
初始化本地 Git 仓库

`1`	`git init`

配置 Git 用户信息
第一次使用 Git 需要告诉它你是谁，否则提交时会报错。运行以下两条命令，替换成你自己的邮箱和名字：

1
2

git config --global user.email "your@email.com"
git config --global user.name "Your Name"

邮箱建议和 GitHub 注册时使用的邮箱保持一致，只需要配置一次，以后不用重复操作。

添加 3 个 git remote（GitHub + NAS 双远程）

remote 命名

origin: GitHub 你的GitHub用户名/myblog.git
nas: 群晖裸仓库，用于备份

# 添加GitHub远程
git remote add origin https://github.com/你的GitHub用户名/myblog.git

# 添加群晖NAS裸仓库远程
git remote add nas admin@192.168.*.*:./volume1/git/hugo-blog.git

# 查看远程列表确认
git remote -v

第一次提交 & 推送

# 全部文件加入暂存
git add .
# commit（.gitmodules必须提交！）
git commit -m "init hugo stack theme, split config"
# 本地分支重命名main（GitHub默认main分支）
git branch -M main

# 推送到GitHub
git push -u origin main
# 推送到群晖NAS备份仓库
git push -u nas main

初次运行git push后会弹出 GitHub 登录窗口，点击 Sign in with your browser，浏览器会打开授权页面，点击 Authorize git-ecosystem 完成授权。授权成功后回到命令提示符，推送会自动继续完成。
后续每次写文章提交，统一命令：

git add .
git commit -m "更新：xxx文章"
git push origin main
git push nas main

第四步：Cloudflare Pages 配置（自动构建发布）

1.注册并登录 Cloudflare 控制台 → Workers & Pages → 创建应用 → Pages → 连接 GitHub
2.授权 Cloudflare 访问你的 GitHub 账号，选择仓库你的GitHub用户名/myblog.git,点开始设置
3.构建配置（关键）

项目	值
生产分支	main
构建框架	hugo
构建命令	hugo
构建输出目录	public
Hugo 版本环境变量	新增变量：HUGO_VERSION = 0.167.0

所有配置填写完成后，点击 Save and Deploy（保存并部署）。
Cloudflare 开始构建，通常需要 1-3 分钟。页面会实时显示构建日志，看到 Success 说明构建成功。

第五步：绑定自定义域名

构建成功后，Cloudflare 会给你分配一个临时域名，格式类似myblog-abc.pages.dev，已经可以访问了。
接下来把你自己的域名绑定上去。
更新 baseURL
域名绑定成功后，还需要把本地配置里的baseURL改成真实域名，否则站内链接会出现问题。
打开config/_default/hugo.toml，把这一行：

`1`	`baseURL = "/"`

改成你的真实域名：

`1`	`baseURL = "https://yourblog.com/"`

保存后重新推送到 GitHub和Nas

git add .
git commit -m "update baseURL"
git push origin main
git push nas main

推送完成后 Cloudflare 会自动重新构建，几分钟后生效。

第六步：验证部署成功

打开浏览器，访问你的域名，看到博客首页说明一切正常。

第七步：日常更新博客的流程

部署完成后，以后每次在本地写完文章或修改了任何内容，按以下流程提交到 GitHub，Cloudflare 会自动重新构建并发布。

第一：本地预览确认没问题

在推送之前，先在本地预览一下确认内容正常：

`1`	`hugo server -D`

打开浏览器访问http://localhost:1313，确认文章显示正常后，按Ctrl + C停止本地服务器。

第二：提交并推送

git add .
git commit -m "更新说明"
git push origin main
git push nas main

第三：等待 Cloudflare 自动构建

推送成功后，Cloudflare 会自动检测到 GitHub 仓库有更新，开始重新构建。通常 1-3 分钟后刷新你的博客页面，就能看到最新内容。

如何确认构建状态？ 登录 Cloudflare Dashboard，进入Workers & Pages,点击你的项目，在Deployments标签里可以看到每次构建的状态和日志。构建成功显示Success,失败显示Failed并附有错误日志。

一键推送脚本

在myblog根目录下新建文件：push.bat,复制以下内容进去保存：

@echo off
chcp 65001 >nul
set "dt=%date:/=-% %time::=-%"
git add .
git commit -m "auto update %dt%"
git push github master
git push nas master
echo.
echo ====== 推送完成 ======
pause

以后每次写完博客在目录双击push.bat就会自动发送。

怎么写博客

常用命令

新建文章

1
2

hugo new posts/文章别名.md（单文章）
hugo new posts/文章别名/index.md（里面包：文章+图）

预览

`1`	`hugo server -D`

内容强调

`1`	` 需强调的内容 `

语法：单个反引号` 包裹文字。

⚠️ 注意符号是键盘左上角那个反引号 `，不是单引号“’”
插入表格

1
2
3

| 第一列 | 第二列 | 第三列 |
|:---:|:---:|:---:|
| 项目名称 | Project  | myblog |

语法说明
1.第一行：表头，| 分隔单元格
2.第二行分隔线：---- 代表这一列，可加 : 控制对齐

|:---| 左对齐（默认）

|:---:| 居中对齐

把文章目录从 post 改成 posts

需要同步修改的四个地方：
1. 重命名目录本身

1
2

# Windows
move content/post content/posts

2. 同步修改permalinks配置
打开config/_default/hugo.toml:

1
2
3

[permalinks]
    posts = "/p/:slug/"
    page  = "/:slug/"

把原来的post = "/p/:slug/"改成posts = "/p/:slug/"，键名要和目录名完全一致。
3. 同步修改mainSections（最容易漏改的一步）
打开config/_default/params.toml，找到顶层的mainSections字段：

`1`	`mainSections = ["posts"]`

4.把原来的["post"]改成["posts"]
这一步最容易漏改——mainSections 决定了首页和归档页去哪个目录抓取文章列表，如果这里还是旧的 post，Hugo 找不到对应目录，首页和归档页的文章列表会直接显示为空，但不会报错，容易让人摸不着头脑。

创建带Front Matter的模板文件

先搞清楚：Front Matter 是什么，为什么长这样

每篇文章最上面，被---夹住的那一段——写标题、日期、分类的地方——就是Front Matter。它跟正文内容是分开存放的，Hugo 靠这段信息知道这篇文章叫什么、归到哪个分类、该生成什么样的网址。
这里要提一句容易让人犯迷糊的地方：Hugo 支持三种 Front Matter 写法,靠开头结尾的分隔符区分：

| 格式 | 分隔符样式 | 示例标题写法 |
| ---- | ---- | ---- |
| YAML | `---` | `title: "标题"` |
| TOML | `+++` | `title = "标题"` |
| JSON | `{ }` | `"title": "标题"` |

三种本质上是同一件事的三种写法，效果完全一样。

容易搞混的地方： 配置文件（hugo.toml、params.toml这些）本身就是纯 TOML 格式，不需要+++包裹；但文章顶部的 Front Matter 我们用的是 YAML，需要 ---包裹。两者是不同场景下的不同格式，名字像、用法不一样，别混着记。
Yaml：使用 — 作为开始和结束的分隔符。

---
title: "文章标题"
date: 2024-05-18T10:00:00+08:00
draft: false
tags: ["Hugo", "前端"]
categories: ["技术博客"]
description: "这是一篇介绍 Hugo Front Matter 的文章"
weight: 10
slug: "hugo-front-matter"

# 自定义参数建议放在 params 下
params:
  author: "张三"
  cover: "/images/cover.jpg"
  series: "Hugo 教程"
---

# 正文从这里开始

Toml：使用 +++ 作为开始和结束的分隔符

+++
title = "文章标题"
date = 2024-05-18T10:00:00+08:00
draft = false
tags = ["Hugo", "前端"]
categories = ["技术博客"]
description = "这是一篇介绍 Hugo Front Matter 的文章"
weight = 10
slug = "hugo-front-matter"

[params]
  author = "张三"
  cover = "/images/cover.jpg"
  series = "Hugo 教程"
+++

# 正文从这里开始

Json：整个 Front Matter 是一个 JSON 对象，{ 必须在第一行，} 单独占一行，后面空一行再写正文。

{
  "title": "文章标题",
  "date": "2024-05-18T10:00:00+08:00",
  "draft": false,
  "tags": ["Hugo", "前端"],
  "categories": ["技术博客"],
  "description": "这是一篇介绍 Hugo Front Matter 的文章",
  "weight": 10,
  "slug": "hugo-front-matter",
  "params": {
    "author": "张三",
    "cover": "/images/cover.jpg"
  }
}

# 正文从这里开始

创建模板

打开myblog/archetypes/目录，新建（或修改已有的）posts.md:

---
title: "{{ replace .File.ContentBaseName "-" " " | title }}"
date: {{ .Date }}
lastmod: {{ .Date }}
pinned: false
weight: -100
draft: false
description: ""
keywords: []
categories:
  - Hugo建站指南
tags:
  - Hugo
series: [""]
series_order: 0
url: ""
image: ""
---



<div style="position:relative; padding-bottom:56.25%; height:0; overflow:hidden; border-radius:12px; margin:16px 0;">
<iframe style="position:absolute; top:0; left:0; width:100%; height:100%;" 
src="https://player.bilibili.com/player.html?bvid=BVxxxxxx" 
frameborder="0" allowfullscreen>
</iframe>
</div>

draft，表示这篇文章是否为草稿，true代表真，false代表假，为真时服务器不生成该页面，用户看不到。所以发布前需设置为假false

description：是文章摘要介绍，Stack主题中显示在标题的下方，它不仅可以吸引阅读者的目光，也是给搜索引擎和分享卡片看的摘要，虽然它不会直接提高你的排名，但会极大影响用户的点击率 (CTR)

keywords：纯粹给 SEO 用的，跟正文里出不出现这些词没关系，但建议跟标题、描述里的词呼应一下.

<div>······</div>里面字段是用来嵌入B站视频的，把 BVxxxxxx 替换成你 B 站视频真实 BV 号。

✅ BV 号获取方法（电脑网页端 + 手机 APP 端）

BV 号规则：以 BV 开头，后面是字母 + 数字，例如 BV1xx411c7mZ，直接提取这一串，放到你之前 B 站 iframe 代码里。

🖥️ 电脑网页端（最推荐，写博客常用）:浏览器打开 B 站视频页面，地址栏链接类似：
https://www.bilibili.com/video/BV1xx411c7mZ/?spm_id_from=xxx,/video/ 后面、? 前面这一段就是 BV 号：BV1xx411c7mZ。

📱 B 站手机 APP:打开视频，点右下角分享箭头,1. 选择「复制链接」，拿到短链接：https://b23.tv/BV1xx411c7mZ, b23.tv/ 后面就是 BV 号 BV1xx411c7mZ

image:文章封面图路径

pinned:文章是否置顶，false为不置顶，需要置顶就改为true

weight:列表排序权重，数字越小越靠前，比靠日期排序更可控

toc:这篇要不要显示文章目录,不需要目录值为false

{{ replace .File.ContentBaseName "-" " " | title }}：自动把文件名（比如 my-first-post）转成标题格式（My First Post），省得每次手动打标题，但中文标题建议还是手动改一下，自动转换对中文不友好。

date: {{ .Date }}：自动填入新建时间。

Hugo中怎么有效的组织文件

方法就是使用Page Bundle，它是Hugo 官方推荐的文件组织方式
Page Bundle（也叫页面捆绑包）：就是把一篇文章（.md 文件）和它相关的所有资源文件（如封面图、图片、内嵌图片等）放在同一个文件夹里。
这样 Hugo 会自动把这个文件夹识别为“一整篇文章”，资源和文章内容紧密绑定，不需要再写复杂的相对路径或纠结 assets / static 的问题。

简单结构示例

content/
└── posts/
    └── my-first-post/          ← 这就是一个 Page Bundle 文件夹
        ├── index.md            ← 文章正文（必须叫这个名字）
        ├── cover.jpg           ← 封面图
        ├── image-1.jpg         ← 文章内使用的图片
        └── image-2.png

如何使用（最简单步骤）

1.新建 Page Bundle

在 content/posts/（或其他分类目录）下新建一个文件夹（文件夹名建议用英文、短横线混合定义，如 my-first-post）。
在文件夹里新建 index.md 文件，把文章内容写进去。
放图片
直接把封面图和其他图片拖进这个文件夹，和 index.md 放在同一层级。
2.Front Matter 中引用
YAML

---
title: 我的文章标题
date: 2026-06-01
image: "cover.jpg"     # ← 只需要写文件名，不用写路径！
---

3.在文章正文中引用图片
Markdown

`1`	`![图片描述](test-pic.webp) ← 这里是Stack主题下的写法`

Hugo 会自动在同文件夹里查找对应的图片文件。

从单文件转换成 Page Bundle（最常用操作）

如果想将已有的单个文件，转换为Page Bundle 结构，按照下面步骤操作即可。

新建一个文件夹（比如 my-post）。
把原来的 my-post.md 改名为 index.md 放进文件夹。
把封面图也放进同一个文件夹。
更新 Front Matter 中的 image 字段，只保留文件名即可，这样就完成了转换。

一句话总结： Page Bundle = 把文章和它的图片打包成一个文件夹，Hugo 自动认领，同级目录下直接用文件名引用。简单、省心、不容易出错，是 Hugo 中长期维护内容的推荐做法。

Hugo on 凡人尘筑