本手册是针对当前 Hexo + Butterfly 主题博客的完整操作指南，涵盖从写文章到上线的全流程。

一、博客项目概览

1.1 技术栈

组件 说明
博客框架 Hexo 5.4.2
主题 Butterfly 5.5.4
部署方式 hexo-deployer-git → GitHub Pages
站点地址 https://gao-youyi.github.io/
本地项目路径 D:\blog\root
源码仓库 本地 Git 管理

1.2 目录结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
D:\blog\root\
├── _config.yml              # Hexo 主配置（站点信息、部署、插件）
├── _config.butterfly.yml    # Butterfly 主题配置（外观、功能）
├── package.json             # 依赖管理
├── scripts/
│   └── blogbot.js           # 自定义脚本（新建、格式化、发布、提醒）
├── source/
│   ├── _posts/              # 所有文章（.md 文件）
│   ├── images/              # 全局图片资源
│   ├── categories/          # 分类页
│   ├── about/               # 关于页
│   └── tags/                # 标签页
├── public/                  # 生成的静态文件（hexo g 产出）
├── .deploy_git/             # 部署工作目录（hexo d 使用）
└── themes/
    └── butterfly/           # 主题文件

1.3 常用命令速查

操作 命令
新建文章（原生） npx hexo new post "文章标题"
新建文章（自定义脚本） npm run blog:new -- "文章标题"
本地预览 npx hexo server 或 npx hexo s
清理缓存 npx hexo clean
生成静态文件 npx hexo generate 或 npx hexo g
部署到 GitHub npx hexo deploy 或 npx hexo d
一键发布 npm run blog:publish
格式化文章 npm run blog:format
博客提醒 npm run blog:remind

二、写博客：从新建到发布

2.1 方法一：使用自定义脚本（推荐）

自定义脚本 blogbot.js 封装了完整的文章管理流程，默认分类为「日常记录」，默认标签为「随笔」「Hexo」。

新建文章草稿：

1
2
3
4
5
# 新建一篇带默认模板的文章
npm run blog:new -- "我的新文章"

# 指定日期
npm run blog:new -- "回顾文章" --date 2026-03-29

脚本会在 source/_posts/ 下生成一个以日期命名的 .md 文件，例如 2026-03-29.md。文件自带以下 front-matter 和正文模板：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
---
title: '我的新文章'
date: '2026-03-29 12:00:00'
updated: '2026-03-29 12:00:00'
description: ''
categories:
  - '日常记录'
tags:
  - '随笔'
  - 'Hexo'
toc: true
published: false
---

## 1. 标题

- 结论：
- 要点：
- 行动：

## 2. 细节

## 3. 参考

格式化已有文章：

1
2
3
4
5
6
7
8
# 自动补全缺失的 front-matter 字段
npm run blog:format

# 预览格式化结果（不写入文件）
npm run blog:format -- --dry-run

# 指定文件
npm run blog:format -- source/_posts/2026-03-29.md

一键发布（生成 + 部署）：

1
npm run blog:publish

此命令会自动执行 hexo clean → hexo generate → hexo deploy，并且如果项目有 Git 仓库还会自动 git add + git commit + git push。

2.2 方法二：使用 Hexo 原生命令

新建文章：

1
npx hexo new post "文章标题"

这会在 source/_posts/ 下创建 文章标题.md。由于 _config.yml 中设置了 post_asset_folder: true，同时会自动创建同名文件夹 文章标题/ 用于存放该文章的图片资源。

新建页面（如关于页、分类页）：

1
npx hexo new page "页面名称"

页面文件生成在 source/页面名称/index.md。

2.3 方法三：手动创建

直接在 source/_posts/ 下新建 .md 文件，文件名建议以日期开头：

1
2026-03-29-文章标题.md

三、文章 Front-Matter 详解

每篇文章开头必须有一段 YAML 格式的 front-matter，用 --- 包裹：

1
2
3
4
5
6
7
8
9
10
11
12
---
title: '文章标题'
date: '2026-03-29 12:00:00'
updated: '2026-03-29 15:30:00'
description: '文章摘要，会显示在首页文章列表中'
categories:
  - '分类名称'
tags:
  - '标签1'
  - '标签2'
toc: true
---

3.1 各字段说明

字段 是否必填 说明
title 是 文章标题，建议用引号包裹
date 是 创建日期，格式 YYYY-MM-DD HH:mm:ss
updated 否 最后修改日期
description 建议 文章摘要，显示在首页列表和 SEO
categories 建议 文章分类，支持多级（缩进表示子分类）
tags 建议 文章标签，一篇文章可以有多个标签
toc 否 是否显示目录，默认 true
published 否 设为 false 时文章不会出现在生成的站点中

3.2 分类 vs 标签

  • 分类具有层级关系（类似目录结构），一篇文章通常属于一个主分类
  • 标签是平级的（类似关键词），一篇文章可以有多个标签

当前已有的分类（供参考，也可以新建）：

分类 说明
日常记录 随笔、生活记录
教程 操作手册、学习指南
项目复盘 项目总结与回顾
项目实战 具体项目实操记录
产品开发 产品设计与开发
算法与数据结构 算法学习笔记
深度学习 DL 框架与模型
计算机视觉 CV 相关内容
课程作业 课程相关
写作工具 Markdown、排版等
Hexo 博客搭建与配置

3.3 摘要控制

在文章正文中插入 <!--more--> 标记，标记之前的内容会作为首页摘要显示。如果不插入此标记，Hexo 默认截取前一段作为摘要。

1
2
3
4
5
这里是摘要内容，会显示在首页。

<!--more-->

这里是正文内容，需要点击「阅读全文」才能看到。

四、插入图片

博客支持三种图片引用方式。

4.1 方式一：全局图片目录（推荐用于通用图片）

将图片放入 source/images/ 目录，然后在文章中使用绝对路径引用：

1
![图片描述](/images/example.png)

示例：

1
![架构图](/images/architecture.png)

路径以 /images/ 开头，对应 source/images/ 目录。

4.2 方式二：文章资源文件夹（推荐用于文章专属图片）

由于 _config.yml 配置了 post_asset_folder: true，每篇文章可以有一个同名文件夹存放图片。

例如文章为 source/_posts/my-post.md，则图片放在 source/_posts/my-post/ 文件夹中：

1
2
3
4
5
source/_posts/
├── my-post.md
└── my-post/
    ├── screenshot.png
    └── diagram.png

在文章中引用（需要 hexo-asset-image 插件，当前项目已安装）：

1
2
![截图](screenshot.png)
![流程图](diagram.png)

4.3 方式三：外部图床链接

直接使用图片的完整 URL：

1
![外部图片](https://example.com/image.png)

这种方式不依赖本地文件，但如果外部链接失效图片将无法显示。

4.4 图片操作注意事项

  1. 图片格式：推荐 PNG（截图、图表）或 JPG（照片），尽量压缩后上传以加快加载速度
  2. 命名规范：使用英文和连字符命名，如 cifar10-training-loss.png，避免中文和空格
  3. 存放位置选择：
    • 多篇文章共用的图片 → source/images/
    • 单篇文章专属的图片 → 文章同名文件夹
  4. 大小建议：单张图片建议不超过 500KB，宽图建议不超过 1200px

五、Markdown 常用语法速查

5.1 标题

1
2
3
## 二级标题
### 三级标题
#### 四级标题

5.2 强调

1
2
3
4
**加粗文本**
*斜体文本*
~~删除线~~
<u>下划线</u>

5.3 列表

1
2
3
4
5
6
- 无序列表项 1
- 无序列表项 2
  - 嵌套列表项

1. 有序列表项 1
2. 有序列表项 2

5.4 代码

行内代码：`code`

代码块：

1
2
3
4
```python
def hello():
    print("Hello, World!")
```

支持的语言高亮：python、javascript、java、c、cpp、bash、yaml、json、sql 等。

5.5 引用

1
2
> 这是一段引用文本
> 可以多行

5.6 链接

1
[链接文字](https://example.com)

5.7 表格

1
2
3
| 列1 | 列2 | 列3 |
|-----|-----|-----|
| 内容1 | 内容2 | 内容3 |

5.8 数学公式

行内公式：$E = mc^2$

块级公式：

1
2
3
$$
\frac{\partial f}{\partial x} = 2x + 1
$$

Butterfly 主题默认支持 MathJax 渲染数学公式。

5.9 分割线

1
---

三个连续的连字符即可生成分割线。

六、本地预览与调试

6.1 启动本地服务器

1
npx hexo server

默认访问地址：http://localhost:4000/

指定端口：

1
npx hexo server -p 5000

6.2 调试流程

  1. 修改文章或配置后，刷新浏览器即可看到变化（Hexo 会自动检测文件变更）
  2. 如果修改了 _config.yml 或 _config.butterfly.yml，需要重启服务器：
    1
    2
    # Ctrl+C 停止当前服务器，然后重新启动
    npx hexo server
  3. 如果出现奇怪的缓存问题，先清理再启动：
    1
    npx hexo clean && npx hexo server

七、生成与部署

7.1 标准部署流程

1
2
3
4
5
6
7
8
# 第一步：清理旧的生成文件
npx hexo clean

# 第二步：生成静态文件
npx hexo generate

# 第三步：部署到 GitHub Pages
npx hexo deploy

也可以合并为一条命令：

1
npx hexo clean && npx hexo g && npx hexo d

7.2 一键发布（自定义脚本）

1
npm run blog:publish

该命令自动执行：clean → generate → deploy → git add → git commit → git push。

7.3 部署原理

  1. hexo generate 将 source/ 下的 Markdown 文件渲染为 HTML，输出到 public/ 目录
  2. hexo deploy 将 public/ 的内容复制到 .deploy_git/ 目录，然后 commit 并 push 到 GitHub
  3. GitHub Pages 自动从 master 分支发布网站内容
  4. 通常几秒钟到几分钟内，线上站点即可更新

7.4 验证部署是否成功

部署完成后访问 https://gao-youyi.github.io/ 检查内容是否更新。

如果内容未更新，可能是 GitHub Pages 缓存，等待 1-2 分钟后刷新。

八、日常维护操作

8.1 修改已有文章

  1. 打开 D:\blog\root\source\_posts\ 下的对应 .md 文件
  2. 编辑内容
  3. 更新 front-matter 中的 updated 字段为当前时间
  4. 本地预览确认无误后，执行部署流程

8.2 删除文章

  1. 删除 source/_posts/ 下的对应 .md 文件
  2. 如有同名资源文件夹，一并删除
  3. 执行 hexo clean && hexo g && hexo d 重新部署

8.3 修改博客配置

配置文件 作用
_config.yml 站点信息、插件、部署设置
_config.butterfly.yml 主题外观、导航、功能开关

修改配置后需要 hexo clean 再重新生成才能生效。

8.4 添加新页面

1
npx hexo new page "页面名称"

然后编辑 source/页面名称/index.md，设置 front-matter：

1
2
3
4
5
---
title: 页面标题
date: 2026-03-29
type: 页面类型
---

如果需要在导航栏显示新页面，编辑 _config.butterfly.yml 中的 menu 配置：

1
2
3
4
5
6
7
menu:
  首页: / || fas fa-home
  分类: /categories/ || fas fa-folder-open
  标签: /tags/ || fas fa-tags
  归档: /archives/ || fas fa-archive
  关于: /about/ || fas fa-heart
  新页面: /新页面/ || fas fa-star

九、博客提醒功能

项目内置了博客写作提醒功能：

1
2
3
4
5
# 手动触发提醒（弹窗 + 邮件）
npm run blog:remind

# 设置定时提醒任务
npm run blog:setup-reminder

提醒功能会：

  • 检查最近的草稿文章
  • 如果没有未完成的草稿，自动创建一个今日模板
  • 弹出 Windows 桌面提醒
  • 发送邮件到配置的邮箱

十、常见问题排查

10.1 hexo generate 似乎卡住不动

在 Trae 终端中，hexo 命令的输出可能被截断，只显示 INFO Start processing。这不代表命令卡住了，实际上命令可能已经正常完成。

验证方法：检查 public/index.html 的修改时间：

1
Get-Item public\index.html | Select-Object LastWriteTime

如果时间是最近的，说明生成成功。

10.2 部署后线上内容未更新

  1. 等待 1-2 分钟，GitHub Pages 可能有缓存延迟
  2. 用 Ctrl+Shift+R 强制刷新浏览器
  3. 检查 .deploy_git 目录下是否有最新提交：
    1
    git -C .deploy_git log --oneline -5

10.3 图片不显示

  1. 确认图片文件确实存在于对应目录
  2. 确认路径大小写正确（Linux 区分大小写）
  3. 全局图片用 /images/xxx.png，文章资源文件夹的图片直接用文件名
  4. 执行 hexo clean 后重新生成

10.4 文章没有出现在首页

  1. 检查 front-matter 中 published 是否被设为了 false
  2. 检查 date 是否是未来时间（_config.yml 中 future: false 会隐藏未来文章）
  3. 执行 hexo clean && hexo g 重新生成

十一、完整工作流示例

以下是一个完整的「写文章并发布」流程：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# 1. 新建文章
npm run blog:new -- "深度学习中的注意力机制"

# 2. 打开生成的文件，编辑内容
#    文件路径会输出在终端，类似 source/_posts/2026-03-29.md

# 3. 手动修改 front-matter 中的分类和标签
#    categories: ['教程']
#    tags: ['深度学习', '注意力机制', 'Transformer']

# 4. 如需添加图片，放入 source/images/ 并在文章中引用
#    ![注意力机制图](/images/attention-mechanism.png)

# 5. 本地预览
npx hexo server
# 浏览器打开 http://localhost:4000 检查效果

# 6. 确认无误后，部署发布
npx hexo clean && npx hexo g && npx hexo d

# 7. 访问 https://gao-youyi.github.io/ 确认线上效果

或者使用一键发布：

1
2
3
npm run blog:new -- "深度学习中的注意力机制"
# 编辑文章...
npm run blog:publish