关于这个系列

Butterfly 提供了完整的 Hexo 博客基础结构，但真正把它变成个人网站，需要理解配置层级、页面结构、资源加载方式和主题升级边界。

这个系列以本站的实际改造过程为例，从一个刚刚初始化的 Hexo 项目开始，逐步完成基础页面、明暗主题、一图流背景和自定义组件，最后讨论如何把不断积累的定制内容整理成独立主题。

教程默认采用“配置优先、注入扩展、避免修改主题包”的方式。这样既能继续升级 Butterfly，又能让个人代码保持清晰。

系列目录

01 · 安装、配置与本地预览

从空目录创建 Hexo 项目，安装 Butterfly，理解 _config.yml、_config.butterfly.yml 与文章 Front Matter，并完成第一次本地预览。

阅读第一篇：安装、配置与本地预览

02 · 导航、首页与文章页

逐项配置菜单、个人信息、首页卡片、摘要、封面、目录、侧栏和页脚，建立完整的网站信息架构。

阅读第二篇：导航、首页与文章页配置

03 · 一图流背景与明暗主题

统一页首、正文和页脚背景，为桌面与手机准备不同图片，并加入平滑的明暗主题切换和适量氛围动画。

阅读第三篇：一图流背景与明暗主题

04 · 使用 Inject 添加自定义组件

讲清楚 Butterfly 的资源注入、组件初始化、PJAX 生命周期、缓存版本和移动端降级，为后续组件开发建立统一模板。

阅读第四篇：使用 Inject 添加自定义组件

05 · 本站自定义组件合集

集中介绍音乐播放器、分类磁贴、标签星座、全局搜索、封面图池、页脚状态和更新日志等组件，以及它们是否只能用于 Hexo。

阅读第五篇：本站自定义组件合集

06 · 从 Butterfly 定制走向独立主题

识别当前网站对 Butterfly 的依赖，设计配置结构、模板目录和迁移顺序，在不影响现有网站的情况下逐步建立个人主题。

阅读第六篇：从定制走向独立主题

推荐阅读方式

第一次搭建博客时，建议按照编号顺序阅读。已经拥有 Butterfly 博客的读者，可以从第三或第四篇开始，但仍建议先了解第一篇中的三个配置层。

每完成一篇，先运行：

1
2
3
npm run clean
npm run build
npm run server

在桌面端和手机尺寸下检查效果，再进入下一阶段。涉及 JavaScript 的组件还需要测试普通刷新和 PJAX 页面跳转。

适用范围

本文示例主要基于：

  • Hexo 7.3
  • Butterfly 5.4
  • npm 安装主题
  • Markdown-it 渲染器
  • Git 部署

配置思路同样适用于相近版本，但具体字段应以对应版本的 Butterfly 官方配置为准。

参考资料与声明

本系列参考官方文档，并结合本站的实际配置、故障排查和组件开发过程重新整理。部分结构与文字由 AI 协助完成，示例均以本项目的实际实现为基础。