零基础搭建个人博客——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 文件，

推荐做法：

• 在 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。
在命令提示符里输入（把路径换成你想要的位置，使用命令创建或资源管理器中直接创建均可）：

1
2
3
4
5
6
7

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

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

1
2
3
4
5
6
7
8

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 文件添加刚刚下载的模板

1
2
3
4

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/ 文件夹，里面有这几个文件：

1
2
3
4
5
6
7

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"

第三：修改以下五项配置

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

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

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

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

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

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

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

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

1

content/page/about/index.zh.md

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

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

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

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

1
2
3
4
5

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

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

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

确认固定页面已到位
前面复制 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账号吧，没有就自己注册一个，然后创建仓库

第二步：处理主题的 .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 [email protected].*.* -p 122(1222是群辉的SSh端口）

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

1
2
3
4
5
6

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

退出群晖 ssh

1

exit

群晖远程仓库地址：[email protected].*.*:./volume1/git/hugo-blog.git

本地初始化 Hugo 站点 myblog

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

1

git init

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

1
2

git config --global user.email "[email protected]"
git config --global user.name "Your Name"

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

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

remote 命名

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

1
2
3
4
5
6
7
8

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

# 添加群晖NAS裸仓库远程
git remote add nas [email protected].*.*:./volume1/git/hugo-blog.git

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

第一次提交 & 推送

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# 全部文件加入暂存
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 完成授权。授权成功后回到命令提示符，推送会自动继续完成。
后续每次写文章提交，统一命令：

1
2
3
4

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.构建配置（关键）

所有配置填写完成后，点击 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

1
2
3
4

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停止本地服务器。

第二：提交并推送

1
2
3
4

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,复制以下内容进去保存：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

@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 写法,靠开头结尾的分隔符区分：

1
2
3
4
5

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

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

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

---
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：使用 +++ 作为开始和结束的分隔符

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

+++
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 对象，{ 必须在第一行，} 单独占一行，后面空一行再写正文。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

{
  "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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

---
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 的问题。

简单结构示例

1
2
3
4
5
6
7

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

1
2
3
4
5

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

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

1

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

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

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

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

1
2
3
4

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

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

给你的博客装修：Stack V4 主题个性化配置指南