Hexo-Butterfly 主题 Preloader 加载页定制
在最初使用 Butterfly 时,为了加速页面的展示速度,减少等待焦虑,我一度拒绝使用全局加载页。但是由于近期博客集成了 站内文章Keycloak,在检查、维护登录态的环节中,不可避免要经历页面被重新刷新的环节。对于普通用户来说,这个莫名其妙的重刷新是非常影响体验的,于是我想到了重新引入全局加载页进行「遮丑」,优化体验。
本文的主要内容:
- 介绍 Hexo-Butterfly 主题全局加载页的逻辑
- 魔改 Hexo-Butterfly 主题源代码,使其更容易加入更多全局加载配置
- 介绍我移植成功的两个 Codepen 全局加载页项目。更多项目可参考 @Akilarの糖果屋关于Loading Animation 的文章。


Hexo-Butterfly 主题默认的全局加载页
Butterfly 主题原生自带加载页的功能,我们只需要在主题配置 _config.butterfly.yml 中开启即可:
1 | # 加载动画 Loading Animation |
当 preloader 开启,并且 source 选择为 1 时,主题会使用默认的全局加载页面,展示结束后会从两边摊开形成双开门效果。

让 Hexo-Butterfly 支持更多的全局加载页
模板侧的修改(Pug)
下面我们通过代码重构,使 Butterfly 支持更多的全局加载页。首先打开 \themes\butterfly\layout\includes\loading\index.pug 修改为以下内容:
1 | if theme.preloader.enable |
主要修改点:
- 前半部分
if-else逻辑修改,这样我们就可以通过主题配置文件中的source字段,选择我们要使用的全局加载页。 - 后半部分是控制全局加载页的启闭代码。原本是放在主题默认的
themes\butterfly\layout\includes\loading\fullpage-loading.pug中。把这段逻辑抽出来放在这是为了更好地统一控制全局加载页的启闭。
样式侧的修改(Stylus)
相应的,我们还需要支持样式文件的按需加载。打开 \themes\butterfly\source\css\_layout\loading.styl,将代码修改为:
1 | // 可以拓展更多的 if-else |
我们做了什么?原本在这个文件中,主题直接将默认的全局加载页的样式放到这里。而现在我们要对其进行多配置的改造。因此我们需要将这个文件定位为一个样式加载的入口,这个入口会根据主题的配置选择性的加载样式文件。这些样式文件都放在 \themes\butterfly\source\css\_layout\loading\ 目录下。
原先主题自带的全局加载页样式,我们可以另外新建文件 ./loading/fullpage-loading 放到里面,作为一个备选项。
新增全局加载页
如果我们需要新增全局加载页并应用它,我们需要做的是:
- 准备好全局加载页的
pug模板和styl样式文件 - 分别将它们放到正确的位置,位置取决你的代码中怎么写。如果你按照上一章节已经改好了模板和样式的入口文件,那么:
- 将
pug模板放在\themes\butterfly\layout\includes\loading\中 - 将
styl样式放在\themes\butterfly\source\css\_layout\loading\中
- 将
- 修改以下入口文件的
if-else逻辑,自己分配匹配的source号:\themes\butterfly\layout\includes\loading\index.pug\themes\butterfly\source\css\_layout\loading.styl
- 主题配置文件
_config.butterfly.yml中开启Preloader并选择相应的source即可。
至于全局加载页,我们可以自己做一套出来,或者参考 Codepen 现成项目进行移植。 @Akilarの糖果屋关于Loading Animation 的文章中详细的讲述了这一方法,并给出了它移植好的几套全局加载页。接下来我将分享我自己移植的两个全局加载页以及移植思路。
波浪加载页


这样的项目 HTML 结构很简单、而且是纯 CSS 项目。直接喂 AI 就能直接生成好 pug 和 styl 的代码。我在这个项目中额外添加的样式以及优化的功能:
- 夜间模式的支持;
- 移除掉原项目中引用网络 SVG 图片,直接将 SVG 图片代码嵌入 PUG 模板中;
- 动画性能优化;
- 全局加载页的消失效果:波浪从下面开始消失,背景清晰度变化;
- 如遇页面重新刷新,波浪不会从头来,保证波浪平滑;
- 其他样式优化(调快动画速度)。
对于你想增加的效果,你可以叫 AI 帮你微调即可。
1 | script. |
1 | // ====================================================== |
我选择波浪全局加载页和向下消失的逻辑,算是呼应上 站内文章海浪页脚 了…
Check List 加载页

对于这一个项目,我也没有做太多修改,主要为:
- 移除原项目中无关内容
- 保留双开门效果
注意到,原项目中它是一个 HTML+CSS+JavaScript 的项目。对于 JavaScript,你可以通过 inject 引入这个脚本。但是为了提高耦合性,我建议将 JavaScript 写入到 pug 模板中。
1 | // https://codepen.io/hoqqanen/pen/zvqGEG |
1 | gold = #FFB900 |
拓展
自主控制全局加载页的关闭时机
下面这段代码是主题默认的控制全局加载页的逻辑:
1 | script. |
这段代码的作用:
- 定义加载控制对象
preloader,设置好启闭函数 preloader.initLoading()决定了一进页面就开始加载- 后面的
if-else函数控制关闭加载页面的逻辑:- 如果页面已经加载完成,直接关闭
- 所有资源(图片、视频、样式)都加载完、DOM 结构渲染完,直接关闭
- 兜底逻辑:7 秒后强制关闭。防止网络异常导致 loading 永远不消失。
- 最后一个
if:PJAX 无刷新跳转支持
如果我们需要自己控制全局加载页的关闭时机,就需要注释掉 if-else 中的逻辑,并把 preloader.endLoading 暴露给外界进行调用。具体更改如下:
1 | script. |
这样,外部的自定义 JavaScript 脚本可以通过以下方式执行全局加载页的关闭:
1 | // 执行加载页的关闭 |
后记
@Akilar 不愧是 Butterfly 魔改老祖。那个时候生成式 AI 还没有大规模应用,他直接就手搓出一个机甲风炫酷博客,到现在四年过去,它的魔改教程依然具备极高的参考价值。我只能说非常的🐮B!

在项目移植过程中,我们自身需要理解好 Butterfly 是如何处理全局加载页,并喂给模型相应示例,才可能得到一个想要的结果。对于复杂移植过程,不同水平的 AI 能力高下立判。每次都得捏着鼻子运行低级模型生成的💩,导致提示词越写越没有耐心。令人惊讶的是,Gemini 3 Pro 生成的代码总能达到满意的水平,以至于每当限额时间解除时,我都会抱着一种毕恭毕敬的心理,像向上帝乞讨那样,规整地整理我的诉求🌚。
这篇文章不是我第一个 AI 重塑博客的项目,还有更多的博客日程近期将陆续上线~





