我的 Hexo 博客项目结构详解

本文将对本站（基于 Hexo + AnZhiYu 主题）的完整项目目录结构进行详细解析，帮助理解每个模块的作用与协作关系。

项目概览

本站是一个基于 Hexo 框架搭建的静态博客，使用 AnZhiYu 主题，通过 Vercel 进行自动部署。包管理器选用 pnpm。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
myBlogs/
├── .github/              # GitHub Actions 工作流配置
├── node_modules/         # 依赖包
├── scaffolds/            # 文章模板
├── source/               # 博客源文件（核心内容）
├── themes/               # 主题目录
│   └── anzhiyu/          # AnZhiYu 主题
├── _config.yml           # Hexo 主配置文件
├── _config.anzhiyu.yml   # anzhiyu 主配置文件
├── _config.landscape.yml # Landscape 主题默认配置（未使用）
├── db.json               # Hexo 数据库缓存
├── package.json          # 项目依赖与脚本
├── pnpm-lock.yaml        # pnpm 锁文件
├── pnpm-workspace.yaml   # pnpm 工作区配置
└── vercel.json           # Vercel 部署配置

各模块详解

1. _config.yml — Hexo 主配置文件

这是整个项目的核心配置，控制着博客的一切行为。主要包括以下几个板块：

配置板块 作用
Site 站点基本信息：标题、副标题、描述、作者、语言、时区等
URL 站点地址、永久链接格式、URL 美化设置
Directory 源文件目录、输出目录、标签/归档/分类目录等
Writing 文章写作配置：默认布局、代码高亮、外部链接行为等
Index Generator 首页文章生成器：每页文章数、排序方式
Pagination 分页配置
Extensions 扩展配置：主题名称
Deployment 部署配置

2. _config.anzhiyu.yml — AnZhiYu 主题配置文件

Hexo 支持通过 _config.[主题名].yml 的方式管理主题配置，该文件即 AnZhiYu 主题的专属配置，优先级高于主题目录内的 _config.yml。此文件内容庞大，涵盖主题外观与功能的方方面面，主要配置板块如下：

配置板块 关键字段 说明
导航菜单 menu 顶部导航栏的项目、图标与链接
代码块 highlight_theme highlight_copy highlight_shrink 代码高亮风格（pale night 等）、复制按钮、默认折叠
社交图标 social 侧边栏社交平台链接与图标
搜索 algolia_search local_search docsearch 站内搜索方案，支持 Algolia / 本地搜索 / DocSearch
图片 favicon avatar index_img cover 网站图标、头像、首页 Banner、文章封面等图片资源
文章 toc post_copyright reward related_post 目录（TOC）、版权声明、打赏、相关推荐
侧边栏 aside 作者卡片、公告、最近文章、分类、标签、归档等组件开关
评论系统 comments waline valine twikoo giscus 评论方案，支持 Waline / Valine / Twikoo / Giscus 等
分享 sharejs addtoany 文章分享按钮
页脚 footer 版权年份、运行时间、徽标、备案信息、子标题打字效果
统计分析 umami_analytics baidu_analytics google_analytics 站点访问统计，当前使用 Umami
美化效果 theme_color beautify font subtitle 主题色、美化样式、字体、首页副标题打字机效果
背景特效 canvas_ribbon canvas_fluttering_ribbon fireworks click_heart 彩带、粒子、烟花、爱心等背景/点击特效
暗/亮/阅读模式 darkmode readmode display_mode 暗色模式自动切换、阅读模式、默认显示模式
右下角按钮 translate rightside_item_order 简繁转换、按钮排序
灯箱 fancybox medium_zoom 图片大图查看，二选一
其他功能 pjax lazyload instantpage pangu snackbar 页面无刷新跳转、懒加载、预加载、中英文间距、Toast 弹窗
CDN CDN 主题内部与第三方脚本的 CDN 源配置
代码注入 inject 自定义 CSS/JS 注入到 </head> 或 </body> 前

提示：该文件中大部分功能默认关闭（enable: false），可按需启用。日常调整最频繁的板块通常是导航菜单、图片资源、侧边栏组件和评论系统。

3. source/ — 博客源文件

这是博客内容的存放地，也是日常写作最常打交道的目录。

1
2
3
4
5
6
7
8
source/
├── _posts/               # 文章存放目录
│   ├── hello-world.md    # Hexo 初始化生成的示例文章
│   └── ...               # 其他文章
├── categories/           # 分类页面
│   └── index.md          # 分类页入口
└── tags/                 # 标签页面
    └── index.md          # 标签页入口

每篇文章以 Markdown 文件形式存储，文件头部使用 Front Matter 定义元数据（标题、日期、标签、分类等）。后续新增文章也都会存放在 _posts/ 目录下。

若需要创建独立页面（如 About、Links 等），可以在 source/ 下直接创建对应目录和 index.md。

4. scaffolds/ — 文章模板

存放新建文章/页面时使用的模板，定义了 Front Matter 的默认结构：

模板文件 用途 默认字段
post.md 新建文章模板 title、date、tags
page.md 新建页面模板 title、date
draft.md 新建草稿模板 title、tags

使用 hexo new post "文章标题" 时，Hexo 会根据 post.md 模板生成新文件。

5. themes/anzhiyu/ — AnZhiYu 主题

这是博客的”皮肤”和”骨架”，决定了博客的视觉呈现和交互行为。AnZhiYu 是一款基于 Butterfly 二次开发的 Card UI 风格主题，在原版基础上增加了大量特色功能。

5.1 主题目录结构

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
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
themes/anzhiyu/
├── _config.yml        # 主题专属配置（外观、功能开关等）
├── layout/            # 页面模板（Pug 模板引擎）
│   ├── index.pug      # 首页模板
│   ├── post.pug       # 文章详情页模板
│   ├── page.pug       # 独立页面模板
│   ├── archive.pug    # 归档页模板
│   ├── category.pug   # 分类页模板
│   ├── tag.pug        # 标签页模板
│   └── includes/      # 模板组件片段
│       ├── head.pug          # HTML <head> 部分
│       ├── footer.pug        # 页脚
│       ├── layout.pug        # 基础布局骨架
│       ├── sidebar.pug       # 侧边栏
│       ├── rightside.pug     # 右下角工具按钮
│       ├── pagination.pug    # 分页组件
│       ├── additional-js.pug # 额外 JS 注入
│       ├── bbTimeList.pug    # 说说/哔哔时间线
│       ├── categoryGroup.pug # 分类分组展示
│       ├── mourn.pug         # 哀悼模式（黑白滤镜）
│       ├── music.pug         # 音乐播放器
│       ├── shortcutKey.pug   # 快捷键面板
│       ├── 404.pug           # 404 页面
│       ├── head/             # head 子组件
│       ├── header/           # 顶部导航栏
│       ├── loading/          # 加载动画
│       ├── mixins/           # Pug 混入（可复用代码块）
│       ├── page/             # 各类页面片段
│       ├── post/             # 文章页片段
│       ├── third-party/      # 第三方服务集成
│       ├── top/              # 首页顶部区域
│       ├── widget/           # 侧边栏小组件
│       ├── popup/            # 弹窗组件
│       ├── bili-banner/      # B站风格 Banner
│       └── anzhiyu/          # AnZhiYu 特色组件
│           ├── ai-info.pug        # AI 摘要信息
│           ├── clock.pug          # 时钟小组件
│           ├── console.pug        # 控制台面板
│           ├── log-js.pug         # 日志 JS
│           ├── rightmenu.pug      # 右键菜单
│           └── tags-group-all.pug # 标签云分组
├── source/            # 静态资源
│   ├── css/           # 样式文件（Stylus）
│   │   ├── index.styl       # 样式入口
│   │   ├── var.styl         # CSS 变量定义
│   │   ├── _global/         # 全局样式与工具函数
│   │   ├── _highlight/      # 代码高亮主题
│   │   ├── _layout/         # 布局组件样式
│   │   ├── _mode/           # 暗/亮/阅读模式
│   │   ├── _page/           # 各页面类型样式
│   │   ├── _search/         # 搜索样式
│   │   ├── _tags/           # 标签插件样式
│   │   ├── _third-party/    # 第三方组件样式
│   │   └── _extra/          # AnZhiYu 扩展样式
│   │       ├── album/           # 相册页面
│   │       ├── anzhiyu/         # 主题自定义样式
│   │       ├── aside_weixin/    # 微信侧边栏
│   │       ├── catalog_list/    # 目录清单
│   │       ├── categoryBar/     # 分类导航栏
│   │       ├── clock/           # 时钟样式
│   │       ├── code/            # 代码块增强
│   │       ├── commentBarrage/  # 评论弹幕
│   │       ├── console/         # 控制台样式
│   │       ├── essay_page/      # 说说/随笔页面
│   │       ├── fix/             # 各类样式修正与兼容
│   │       ├── footer/          # 页脚增强
│   │       ├── friends/         # 友链页面
│   │       ├── greeting_box/    # 问候框
│   │       └── home_top/        # 首页顶部区域
│   ├── js/            # 脚本文件
│   │   ├── main.js          # 主入口脚本
│   │   ├── utils.js         # 工具函数
│   │   ├── tw_cn.js         # 繁简转换
│   │   ├── search/          # 搜索功能脚本
│   │   └── anzhiyu/         # AnZhiYu 特色脚本
│   │       ├── ai_abstract.js       # AI 文章摘要
│   │       ├── comment_barrage.js   # 评论弹幕
│   │       ├── people.js            # 人物信息
│   │       ├── random_friends_post.js # 随机友链文章
│   │       └── right_click_menu.js  # 右键菜单
│   └── img/           # 主题内置图片
├── scripts/           # 主题脚本（Hexo 插件机制）
│   ├── events/        # 事件处理
│   │   ├── init.js            # 主题初始化
│   │   ├── merge_config.js    # 配置合并
│   │   ├── cdn.js             # CDN 资源加载
│   │   ├── comment.js         # 评论系统处理
│   │   ├── stylus.js          # Stylus 编译配置
│   │   ├── 404.js             # 404 页面处理
│   │   └── welcome.js         # 欢迎信息
│   ├── filters/       # 内容过滤器
│   │   ├── post_lazyload.js   # 图片懒加载
│   │   └── random_cover.js    # 随机封面图
│   ├── helpers/       # 模板辅助函数
│   │   ├── aside_archives.js  # 侧边栏归档
│   │   ├── aside_categories.js# 侧边栏分类
│   │   ├── related_post.js    # 相关文章推荐
│   │   ├── page.js            # 页面辅助
│   │   ├── catalog_list.js    # 目录清单
│   │   ├── inject_head_js.js  # JS 注入
│   │   ├── findArchiveLength.js # 归档长度
│   │   ├── get_version.js     # 版本获取
│   │   ├── random.js          # 随机数工具
│   │   ├── sort_attr_post.js  # 文章属性排序
│   │   ├── tags_page_list.js  # 标签页面列表
│   │   └── year.js            # 年份处理
│   └── tag/           # 标签插件（在 Markdown 中使用的自定义标签）
│       ├── button.js      # 按钮标签
│       ├── note.js        # 提示块标签
│       ├── tabs.js        # 选项卡标签
│       ├── gallery.js     # 画廊标签
│       ├── mermaid.js     # Mermaid 图表
│       ├── hide.js        # 隐藏内容标签
│       ├── label.js       # 标签样式
│       ├── inlineImg.js   # 行内图片
│       ├── flink.js       # 友链标签
│       ├── timeline.js    # 时间线标签
│       ├── bilibili.js    # B站视频嵌入
│       ├── btns.js        # 按钮组
│       ├── checkbox.js    # 复选框
│       ├── dogeplayer.js  # 播放器
│       ├── folding.js     # 折叠面板
│       ├── iconfont.js    # 图标字体
│       ├── image.js       # 图片增强
│       ├── inline-labels.js # 行内标签
│       ├── Introduction-card.js # 介绍卡片
│       ├── link.js        # 链接卡片
│       ├── media.js       # 媒体嵌入
│       ├── site.js        # 站点卡片
│       ├── span.js        # 行内样式
│       └── tip.js         # 提示标签
├── languages/         # 国际化语言文件
│   ├── default.yml    # 默认语言
│   ├── zh-CN.yml      # 简体中文
│   ├── zh-TW.yml      # 繁体中文
│   └── en.yml         # 英文
├── sw-rules.js        # Service Worker 规则（PWA 离线缓存策略）
├── package.json       # 主题依赖声明
└── plugins.yml        # 主题推荐的第三方插件清单

5.2 AnZhiYu 相较于原版 Butterfly 的主要增强

AnZhiYu 在 Butterfly 的基础上增加了许多特色功能：

特色功能 说明
AI 文章摘要 自动生成文章 AI 摘要，展示在文章顶部
评论弹幕 评论以弹幕形式在页面飘过
右键菜单 自定义右键上下文菜单
说说/随笔 类似社交动态的短内容发布
控制台面板 快捷主题设置面板
B站视频嵌入 通过标签直接嵌入 B站视频
时钟组件 侧边栏时钟小组件
标签云分组 标签的可视化分组展示
相册页面 独立的相册展示功能
友链随机文章 随机展示友链博客的文章
问候框 站点问候弹窗
哀悼模式 一键开启全站黑白滤镜

5.3 主题配置要点

AnZhiYu 主题的配置文件功能丰富（即项目根目录的 _config.anzhiyu.yml），主要涵盖：

  • 导航设置：菜单、Logo、固定导航栏
  • 代码块：主题风格、Mac 风格、高度限制、代码复制
  • 图片设置：Favicon、头像、各页面 Banner 图、封面图
  • 首页设置：副标题打字机效果、文章布局模式
  • 文章设置：目录（TOC）、版权声明、打赏、相关推荐
  • 侧边栏：作者卡片、公告、最近文章、分类、标签、归档等
  • 评论系统：支持 Waline、Valine、Twikoo、Giscus 等
  • 搜索：支持 Algolia、本地搜索、DocSearch
  • 美化效果：暗色模式、阅读模式、页面过渡动画、鼠标特效
  • CDN 配置：支持 local / jsdelivr / unpkg / cdnjs / custom

6. package.json — 项目依赖与脚本

核心依赖说明：

依赖包 作用
hexo Hexo 框架核心
hexo-deployer-git Git 部署插件
hexo-generator-archive 归档页生成器
hexo-generator-category 分类页生成器
hexo-generator-index 首页生成器
hexo-generator-tag 标签页生成器
hexo-renderer-ejs EJS 模板渲染器
hexo-renderer-marked Markdown 渲染器
hexo-renderer-pug Pug 模板渲染器（AnZhiYu 主题使用）
hexo-renderer-stylus Stylus 样式渲染器（AnZhiYu 主题使用）
hexo-server 本地开发服务器
hexo-util Hexo 工具库
moment-timezone 时区处理

7. vercel.json — Vercel 部署配置

  • buildCommand：执行 pnpm build（即 hexo generate）生成静态文件
  • outputDirectory：构建产物输出到 public 目录
  • installCommand：安装全局 pnpm 后再安装项目依赖
  • framework：设为 null，因为 Hexo 不属于 Vercel 自动识别的框架

8. 其他文件

文件 作用
.gitignore Git 忽略规则：排除 node_modules/、public/、db.json、.deploy*/ 等
_config.landscape.yml Landscape 主题的默认配置，当前未使用
db.json Hexo 运行时生成的数据库缓存，记录文章和资源元信息
pnpm-lock.yaml pnpm 依赖锁文件，确保依赖版本一致性
pnpm-workspace.yaml pnpm 工作区配置
.deploy_git/ hexo deploy 生成的 Git 仓库，用于推送到 GitHub Pages 等平台
.github/workflows/ GitHub Actions 工作流目录

构建与部署流程

1
2
3
4
5
6
7
8
Markdown 文章 (source/_posts/*.md)
        ↓ hexo generate
    模板渲染 (themes/anzhiyu/layout/*.pug)
    样式编译 (themes/anzhiyu/source/css/*.styl)
        ↓
    静态文件 (public/)
        ↓ Vercel 自动部署
    线上站点
  1. 在 source/_posts/ 中编写 Markdown 文章
  2. 执行 hexo generate（或 pnpm build），Hexo 会结合主题模板和配置，将 Markdown 渲染为完整的 HTML
  3. 生成物输出到 public/ 目录
  4. 代码推送到 GitHub 后，Vercel 自动拉取、构建、部署

常用命令

命令 作用
hexo new post "标题" 新建文章
hexo new page "页面名" 新建页面
hexo server 启动本地预览服务器（默认 http://localhost:4000）
hexo generate 生成静态文件到 public/
hexo clean 清除缓存文件（db.json、public/）
hexo deploy 部署到远程仓库

总结

整个项目的核心工作流非常简洁：写 Markdown → 推送代码 → Vercel 自动构建部署。日常操作只需关注 source/_posts/ 目录下的文章编写和 _config.yml / _config.anzhiyu.yml 中的配置调整。其中 _config.anzhiyu.yml 是主题功能的”控制中心”，涵盖导航、外观、评论、统计等所有主题相关设置。AnZhiYu 主题在 Butterfly 的基础上提供了更多开箱即用的特色功能，后续可根据需要逐步启用 AI 摘要、评论弹幕、说说、相册等功能。