hexo魔改教程(三)
博客搭建与魔改系列教程导航🚥🚥🚥
- hexo基础教程(一)
- hexo魔改教程(一)
- hexo魔改教程(二)
- hexo魔改教程(三)
- hexo魔改教程(四)
- hexo魔改教程(五)
- hexo魔改教程(六)
- 综合美化模块教程
本篇是第 21 ~ 41 个魔改,适用Hexo 8.1.2+Butterfly 5.7.2,末节是升级配置清单。
阅读约定:每个代码块上方都标了 文件 和 改法(终端命令标 执行位置 和 作用,目录树 / 报错 / 示意内容标 说明)。[Blogroot] 指博客根目录;「新建」是建文件后整段写入,「追加」是放到文件末尾,「替换 / 在 xxx 后插入」是在已有文件里改对应位置。改 themes/ 下的模板和脚本前先备份,主题一升级就会被覆盖。
开始之前:一次装齐依赖
本教程里到处在用的折叠块、提示框,以及后面几节用到的插件,一行装齐:
执行位置:博客根目录终端 | 作用:一次装齐本篇反复用到的插件(折叠块、页脚徽标、磁贴、历史日历、轮播、双栏、wowjs),装完 package.json 的依赖里会多出这些包。
1 | npm install hexo-butterfly-tag-plugins-plus hexo-butterfly-footer-beautify hexo-electric-clock \ |
hexo-butterfly-tag-plugins-plus:{% folding %}、{% note %}这些标签由它提供,不装的话整篇文章的折叠块会变成纯文本。- 其余插件是按节按需的,只做某一节就只装那一节(每节开头都单独写了命令)。
- 教程里的
cp是 Linux / macOS 写法,Windows 用copy,或者直接资源管理器里复制粘贴——效果一样。 - 下面所有路径都以
[Blogroot](博客根目录)开头。
炫彩流光文字
炫彩字
新建 [Blogroot]\source\css\brinks.css,写入:
文件:[Blogroot]/source/css/brinks.css | 改法:新建文件,整段写入。
1 | .brinks { |
background-size 用 100vw、位移用 -2000vw,两者是整数倍关系(20 个周期),循环时颜色能接上,不会跳。
在 [Blogroot]\_config.butterfly.yml 的 inject.head 添加:
文件:[Blogroot]/_config.butterfly.yml | 改法:在顶层 inject: 下的 head: 列表末尾追加这一条 <link>;缩进保持两格,和其它 - 项对齐。
1 | inject: |
在 [Blogroot]\_config.butterfly.yml 使用:
文件:[Blogroot]/_config.butterfly.yml | 改法:找到顶层 footer:,在它下面加 custom_text:(缩进两格);已有 custom_text 就整行替换。
1 | footer: |
全站自定义字体
借鉴:Fomalhaut(猕猴桃)的字体本地化思路;字体本身来自
LXGW WenKai(OFL)。本站改动:按需做字体子集,只保留站内实际用到的字形并转成本地woff2。
霞鹜文楷
字体是开源免费的(OFL 协议),从 LXGW WenKai 官方仓库取,转成 woff2 再用:
执行位置:本机终端(不必在博客根目录)| 作用:装字体子集工具,把 LXGWWenKai-Regular.ttf 转成 woff2 并输出到 source/font/;--output-file 要写你自己博客的绝对路径。
1 | # 1) 一次性装好字体转换工具 |
把字体文件放到 [Blogroot]\source\font\霞鹜文楷.woff2 之后,继续往下配。
在 [Blogroot]\source\css\custom.css 末尾添加:
文件:[Blogroot]/source/css/custom.css | 改法:追加到文件末尾。
1 | @font-face { |
在 [Blogroot]\_config.butterfly.yml 配置:
文件:[Blogroot]/_config.butterfly.yml | 改法:顶层 font:、blog_title_font:、beautify: 三个键下的对应项按此改写;myfont 必须和上一步 @font-face 里的 font-family 同名。
1 | font: |
在 [Blogroot]\_config.butterfly.yml 的 inject.head 添加:
文件:[Blogroot]/_config.butterfly.yml | 改法:追加到 inject.head 列表末尾;href 里的中文文件名要用 URL 编码(%E9%9C%9E...)才稳。
1 | inject: |
FontAwesome 图标本地化
图标本地化
不用手动去找 CSS 和字体,装官方 npm 包再拷出来即可:
执行位置:博客根目录终端 | 作用:装 FontAwesome Free 6.5.1,并把 fontawesome.min.css 和三个 woff2 拷进 source/css、source/webfonts。Windows 下 mkdir -p / cp 换成手工建目录、复制粘贴即可。
1 | npm install @fortawesome/fontawesome-free@6.5.1 --save-dev |
拷完是这样(版本号跟着 npm 包里的一致,6.5.1 就是下面这些文件):
把 Font Awesome Free 6.5.1 的三个字体文件放到 [Blogroot]\source\webfonts\:
说明:示意内容,不需要修改——这是上一步拷完后的文件位置清单,用来核对有没有少拷。
1 | source/webfonts/fa-solid-900.woff2 |
把官方 fontawesome.min.css 放到 [Blogroot]\source\css\fontawesome.min.css,其中三个 @font-face 的 src 改成:
文件:[Blogroot]/source/css/fontawesome.min.css | 改法:这是官方 CSS 里三条 @font-face 的片段,只把三条 src 的 url(...) 换成 /webfonts/... 本地路径,其余规则原样保留。
1 | @font-face{font-family:"Font Awesome 6 Free";font-weight:900;src:url(/webfonts/fa-solid-900.woff2) format("woff2")} |
在 [Blogroot]\_config.butterfly.yml 配置:
文件:[Blogroot]/_config.butterfly.yml | 改法:顶层 CDN: 下的 option: 里,把 fontawesome: 的值改成 /css/fontawesome.min.css。
1 | CDN: |
在 [Blogroot]\_config.butterfly.yml 的 inject.head 添加:
文件:[Blogroot]/_config.butterfly.yml | 改法:两条一起追加到 inject.head 列表末尾。
1 | inject: |
菜单图标用 FA6 正式类名:
文件:[Blogroot]/_config.butterfly.yml | 改法:顶层 menu: 列表里按需追加或替换对应项;|| 前后分别是「图标 + 链接」和「悬停图标」,两处图标名要一致。
1 | menu: |
一图流背景与遮罩
借鉴:Fomalhaut(猕猴桃)。本站改动:背景图换成本站
WebP,遮罩透明度单独用变量控制。
一图流
把背景图放到 [Blogroot]\source\img\bg.webp。
在 [Blogroot]\_config.butterfly.yml 配置:
文件:[Blogroot]/_config.butterfly.yml | 改法:顶层逐项改值——background 换成你的背景图路径,index_img / default_top_img 留空(一图流不需要单独封面),footer_img: false,mask: 下两个开关按需改。
1 | background: /img/bg.webp |
在 [Blogroot]\source\css\custom.css 末尾添加:
文件:[Blogroot]/source/css/custom.css | 改法:追加到文件末尾。
1 | [data-theme="light"] #footer::before { background: rgba(255,255,255,.5); } |
在 [Blogroot]\_config.butterfly.yml 的 inject.head 添加:
文件:[Blogroot]/_config.butterfly.yml | 改法:追加到 inject.head 列表末尾。
1 | inject: |
页脚计时器与框架徽标
借鉴:店长(Fomalhaut 整理)。本站改动:插件静态资源改为本地托管,计时起点与徽标列表换成本站配置。
页脚徽标
插件和它要用的静态文件,一条命令装好:
执行位置:博客根目录终端 | 作用:装页脚徽标与计时插件,并把插件自带的 runtime.js、runtime.css、swiperbdage_init.min.js 与 swiper 本体拷进 source/js、source/css。
1 | npm install hexo-butterfly-footer-beautify hexo-electric-clock --save |
装完这些文件应该在对应路径:
说明:示意内容,不需要修改——核对上面命令拷出来的文件是否都在对应路径。
1 | source/js/runtime.js |
在 [Blogroot]\themes\butterfly\layout\includes\layout.pug 的 footer#footer 内补一层容器:
文件:[Blogroot]/themes/butterfly/layout/includes/layout.pug | 改法:找到 footer#footer(...),确认它下面用 #footer-wrap 包住了 !=partial('includes/footer', ...);Butterfly 5.7.2 已自带这两行,缺了才补(缩进两层)。
1 | footer#footer(style=footer_bg) |
在 [Blogroot]\source\css\custom.css 末尾添加:
文件:[Blogroot]/source/css/custom.css | 改法:追加到文件末尾。
1 | #footer #footer-wrap > * { position: relative; color: var(--light-grey); } |
在 [Blogroot]\_config.butterfly.yml 配置:
文件:[Blogroot]/_config.butterfly.yml | 改法:在文件末尾新增顶层 footer_beautify: 段(插件只认顶层键,别缩进到别的键下面)。
1 | footer_beautify: |
小冰分类磁贴
借鉴:小冰(Fomalhaut 整理)。本站改动:分类名称、图标与分栏按本站栏目重排。
分类磁贴
在 [Blogroot]\_config.yml 配置:
文件:[Blogroot]/_config.yml | 改法:在文件末尾新增顶层 magnet: 段;display 里的 name 必须和你的真实分类名完全一致,否则那格是空的。
1 | magnet: |
装插件:
执行位置:博客根目录终端 | 作用:安装分类磁贴插件。
1 | npm install hexo-magnet --save |
装完重启 hexo s,磁贴才会被注入。依赖 [Blogroot]\package.json 里的 hexo-magnet。
历史上的今天
借鉴:小冰(Zfour)。本站改动:只保留接入配置,卡片样式与本站侧栏宽度对齐。
历史上的今天
在 [Blogroot]\_config.yml 配置:
文件:[Blogroot]/_config.yml | 改法:在文件末尾新增顶层 history_calendar:、electric_clock: 两段;layout.name 指向侧栏容器 sticky_layout,不要改成 recent-posts。
1 | history_calendar: |
装插件:
执行位置:博客根目录终端 | 作用:安装历史日历与电子钟插件(电子钟默认 enable: false,想用再开)。
1 | npm install hexo-history-calendar hexo-electric-clock --save |
「历史上的今天」的模板里用到了 swiper 容器,所以要在「页脚计时器与框架徽标」那节把 swiper.min.js / swiper.min.css 也放到 source/js、source/css 下(那一节有完整命令)。
依赖 [Blogroot]\package.json 里的 hexo-history-calendar、hexo-electric-clock。
首页置顶轮播与文章双栏
借鉴:店长 / 小冰(Fomalhaut 整理)。本站改动:轮播与双栏配置按本站首页结构重排,静态资源改为本地加载。
轮播与双栏
在 [Blogroot]\_config.yml 配置:
文件:[Blogroot]/_config.yml | 改法:在文件末尾新增顶层 swiper:、butterfly_article_double_row: 两段;stylus: 是主题自带的压缩开关,已有就只核对值,别重复写。
1 | swiper: |
这一步要两个插件:
执行位置:博客根目录终端 | 作用:安装置顶轮播与首页双栏插件;swiper 本体复用上一节拷进 source/js、source/css 的本地文件。
1 | npm install hexo-swiper-bar hexo-butterfly-article-double-row --save |
在文章 front matter 里写 top: 1。
在 [Blogroot]\source\css\custom.css 末尾添加 5.x 双排适配:
文件:[Blogroot]/source/css/custom.css | 改法:追加到文件末尾(末尾那段 .low-perf 降级规则一并加上)。
1 | @media screen and (min-width: 769px) { |
页脚备案三连(ICP / 公安 / 萌ICP)
备案三连
在 [Blogroot]\_config.butterfly.yml 新增顶层 beian 段:
文件:[Blogroot]/_config.butterfly.yml | 改法:新增顶层 beian: 段(放文件末尾即可);三个编号换成你自己的,还没下号就保持 pending: true。
1 | beian: |
在 [Blogroot]\themes\butterfly\layout\includes\footer.pug 末尾添加:
文件:[Blogroot]/themes/butterfly/layout/includes/footer.pug | 改法:追加到文件末尾,缩进为 0(和已有的 if theme.footer.custom_text 同级)。
1 | //- 备案信息三连 |
在 [Blogroot]\source\css\custom.css 末尾添加:
文件:[Blogroot]/source/css/custom.css | 改法:追加到文件末尾。
1 | #footer-wrap .beian-row { |
pending: true 显示「办理中」不生成链接;下号后填 number / code 并把 pending 改成 false。
昼夜更替(山河日月版)
借鉴:店长(Fomalhaut 整理)。本站改动:过场脚本重写为自包含实现,动画时长与降级策略按本站性能模式调整。
黄昏落幕过场
效果:点右上角的月亮/太阳,整屏不是直接换色,而是走一段「黄昏落幕」——太阳从左上方往右下沉、月亮从左下方往右上爬,星星一颗颗亮起来,远山剪影与地平线余光跟着压暗;切回白天时完全反向(月亮落、太阳升、星星退场)。最后 350ms 从点击处做一个圆形揭幕,把新主题「揭」出来。
核心是一个自包含脚本:DOM、渐变、关键帧全部由 JS 现场创建,不依赖任何外部 CSS,所以换主题皮肤也不会互相打架。
新建 [Blogroot]\source\js\fomal\night.js,写入:
文件:[Blogroot]/source/js/fomal/night.js | 改法:新建文件,整段写入;本站 source/js/fomal/night.js 已经是这份实现,改动时对照补齐即可,不要另建第二份。
1 | /*! |
[Blogroot]\_config.butterfly.yml 的 inject.bottom 加一行:
文件:[Blogroot]/_config.butterfly.yml | 改法:追加到 inject.bottom 列表末尾;defer 要保留,提前执行会拿不到 DOM。
1 | inject: |
按钮用主题自带的那个就行([Blogroot]\themes\butterfly\layout\includes\header\nav.pug):
说明:主题自带按钮的片段,一般不需要修改——要是昼夜切换按钮丢了,就照这段在 themes/butterfly/layout/includes/header/nav.pug(第 34 行附近)恢复。
1 | a.sun_moon.faa-parent.animated-hover(onclick='switchNightMode()', title=_p('rightside.night_mode_title') id="nightmode-button") |
三个坑,踩过就记住:
- 主题自带的
sun_moon.js会定义同名的全局switchNightMode,两份一起跑就是「动画播一半被另一份掐断」。脚本里用Object.defineProperty(window, 'switchNightMode', ...)占住这个全局名,并且加载后 400ms / 1500ms 再赋一次值,防止被异步脚本后覆盖。 - 连点:动画中再点不再被静默丢弃,记一个
pending,本轮收尾后自动补播一次;每次运行带runGen代次,旧一轮的定时器 / rAF 一律作废,不会出现「上一轮把这一轮掐了」。 - 遮罩闪烁:
mask从circle 0直接跳到160vmax再叠一层opacity:0,第一帧会整块消失。改成requestAnimationFrame逐帧写半径,overlay全程opacity:1,结束后才visibility:hidden。
档位(localStorage.darkTransition):off 直接切换/light 800ms 简化/standard 1500ms 默认/flourish 多一颗流星。系统开了「减少动态效果」时保留过场但压到 45% 时长,不做成直接消失。
切换样式:山河日月 / 图形(旧版)
上面那套「黄昏落幕」是后来写的版本,但不少人(包括我自己)还是惦记主题原配那套:整屏青绿→橙黄的渐变圆盘转一圈、日月在同一点叠着做透明度互换。与其二选一删掉一个,不如做成开关。
键:localStorage.hgNightStyle,scene(默认,山河日月)/ cuteen(图形,旧版转盘)。
分工:新版的 DOM、渐变、关键帧全在 night.js 里自建;旧版反过来——只负责插 DOM,动画交给主题自带的 themes/butterfly/source/css/_layout/sun_moon.styl(.Cuteen_DarkSky / .Cuteen_DarkPlanet / #sun / #moon),这些样式本来就编译进主题 CSS,不用补。
1. night.js:读样式 + 分流
文件:[Blogroot]/source/js/fomal/night.js | 改法:三处追加,不要新建第二个文件。
(a) 状态区(var pending = false 后面)加:
1 | var STYLE_KEY = 'hgNightStyle' |
(b) startRun() 里,紧跟「关档直接切主题」那行之后:
1 | if (t === 'off') { applyTheme(toDark); running = false; return } |
(c) 在 bind() 之前插入旧版播放器:
1 | /** |
2. 转盘时长必须走 CSS 变量(本节最坑的一处)
旧版动画在 custom.css 里带了 !important,你就算在 JS 里写 planet.style.animationDuration = '3s' 也完全无效(内联样式优先级低于 !important)。唯一能干过它的是自定义属性:把时长替换成 var(--hg-cut-dur, 1s),再由 JS 写到 .Cuteen_DarkSky 上,让子元素继承。
文件:[Blogroot]/source/css/custom.css | 改法:把旧版那段的动画声明替换掉:
1 | .Cuteen_DarkPlanet { |
(.Cuteen_DarkSky{transition:opacity .75s}、#sun/#moon{transition:opacity .4s} 这些保持原样即可。)
3. 面板里加一行开关
文件:[Blogroot]/source/js/fomal/panel.js | 改法:函数区、HTML 片段、导出与 syncAll() 各加一处。
函数(放在 setTier 之前):
1 | /* ── 昼夜切换样式:山河日月 / 图形(旧版 Cuteen 转盘) ────────────────── */ |
HTML:接在「昼夜切换」那行 </div></div> 之后、互动挂件 标题之前:
1 | '<div class="feature-opt dm-wide"><span>切换样式<small id="nightStyleNote">点击日月的过场效果</small></span>' + |
导出(跟 w.hgSetTier = setTier 放一起):
1 | w.hgSetNightStyle = setNightStyle |
syncAll() 末尾补一行 syncNightStyle()(和 syncTier() 并列),否则重开面板时按钮状态是旧的。
如果面板脚本是从 boot.js 的 KEYS 里取键名,记得补 nightStyle: 'hgNightStyle',;没有 boot.js 就在 panel.js 里直接用字符串 'hgNightStyle' 当键,两处必须一致。
4. 验证
点右上角日月两次,各看一遍:
- 面板选「图形(旧版)」:能截到的中间画面是整屏 青绿→橙黄 渐变盘 + 左侧大太阳;入夜则变成 紫→青 的深色渐变淡入,1000ms 后整块消失。
- 面板选「山河日月」:回到太阳沉落、月亮升起、星星渐显,末尾圆形揭幕。
Console 里 localStorage.hgNightStyle 应该是 scene 或 cuteen;切完主题还能看到 document.querySelector('.Cuteen_DarkSky') 为 null(说明清理干净了)。档位选「关闭」时两种样式都不播动画,只切主题——这是预期行为。
5. 还有一个 hexo 的坑
改了 public/ 下的文件(哪怕只是临时 sed 调试),它的修改时间会比 source/ 新,hexo generate 会跳过复制,于是你以为改好了、其实线上还是旧的。遇到「源码明明改了但页面没变」,先删掉对应 public/js/... 再 generate,最省事。
评论区(Twikoo 私有部署)
借鉴:衍方(Twikoo 作者)的部署思路。本站改动:改为私有部署 + 同源反代,配置与安全项按本站服务器环境重写。
自建评论服务
国外那几家评论服务在国内加载慢、还可能被墙,备案后又要「可管可控」,干脆自己起一个 Twikoo:数据在自己服务器,前端只请求自己的域名(同源反代),不用额外证书。
服务器上 docker-compose.yml:
文件:服务器上的 docker-compose.yml(例如 /root/twikoo/docker-compose.yml,目录自己建)| 改法:新建文件,整段写入后把 <本地端口> 换成实际端口。注意这个文件不在博客目录里。
1 | services: |
<本地端口> 自己挑一个没被占用的端口(比如 6xxx~9xxx 里随便选),把这一行替换掉。
两条铁律:
- 只绑
127.0.0.1:前面带127.0.0.1:就意味着只有本机能连,公网扫不到这个端口。 - 不要写进公开的教程 / 截图里:端口只是内网细节,写出来等于告诉别人从哪儿找入口;外网访问一律走下面的 Nginx 反代(对外只有 443 +
/twikoo/路径)。
保存后启动:
执行位置:服务器上存放 docker-compose.yml 的目录 | 作用:后台拉起 Twikoo 容器,ps 里 STATUS 显示 Up 就正常。
1 | docker compose up -d |
第一次启动会自动拉 imaegoo/twikoo 镜像;拉不动就给 Docker 配国内镜像加速。
Nginx 站点配置里加一段(放在 #REWRITE-START 之前):
文件:服务器 Nginx 的站点配置文件(宝塔面板里是「站点 → 配置文件」)| 改法:在 #REWRITE-START 之前插入这一段,<本地端口> 与 compose 里保持一致。
1 | location ^~ /twikoo/ { |
nginx -t 通过后 nginx -s reload。验证:
执行位置:任意终端(本机或服务器都行)| 作用:POST 一次 GET_FUNC_VERSION,返回 {"code":0,...} 说明反代和容器都通了。
1 | curl -i -X POST https://你的域名/twikoo/ -H "Content-Type: application/json" -d '{"event":"GET_FUNC_VERSION"}' |
返回 {"code":0,...} 就通了。
[Blogroot]\_config.butterfly.yml:
文件:[Blogroot]/_config.butterfly.yml | 改法:顶层 comments: 把 use 改成 Twikoo,再新增顶层 twikoo: 段;envId 结尾的斜杠不能省。
1 | comments: |
管理员面板没有独立网址:评论框右下角那个小齿轮就是入口,第一次点开直接让你设密码(私有部署默认没有 TWIKOO_ADMIN 之类环境变量)。
忘记密码:改容器里的 /app/data/db.json,删掉 config.ADMIN_PASS 这一段,再回面板重设。数据全在 ./data 目录,记得纳入备份;想连评论数一起用,visitor: true 再把 comments.count 打开。
FPS 帧率监测(fomal 药丸版)
借鉴:LYX(Fomalhaut 整理)。本站改动:显示改成右下角药丸,六档状态与低性能模式阈值按本站实现调整。
右下角 FPS 药丸
用 requestAnimationFrame 数帧,每秒算一次,显示成右下角的小药丸:FPS 240 · 流畅,六档(极低/卡顿/偏低/一般/顺畅/流畅)。顺便驱动「低性能模式」:连续两次低于 35 帧就给 html 加 .low-perf,连续五次 50 帧以上再摘掉,方便在 custom.css 里给毛玻璃、动画、画布做降级。
新建 [Blogroot]\source\js\fps.js:
文件:[Blogroot]/source/js/fps.js | 改法:新建文件,整段写入;本站已有同名文件,改逻辑时在它的 stateOf() / loop() 里补全即可。
1 | /* 帧率检测(fomal 样式 + 本站低性能模式) |
[Blogroot]\source\css\custom.css 追加药丸样式:
文件:[Blogroot]/source/css/custom.css | 改法:追加到文件末尾。
1 | html #fps, html[data-theme] #fps { |
[Blogroot]\_config.butterfly.yml 的 inject:
文件:[Blogroot]/_config.butterfly.yml | 改法:inject.head 加 <span id="fps"></span> 容器、inject.bottom 加脚本,两句分别放进对应列表。
1 | inject: |
想随时开关:控制台执行 fpsSwitch(false) 关、fpsSwitch(true) 开,状态存在 localStorage.fpson;也可以接到美化设置面板里做一个开关行。
wowjs 进场动画
借鉴:Fomalhaut(猕猴桃)。本站改动:插件与
CDN资源改为本地加载,动画时长与PJAX重载按本站流程调整。
滚动入场动画
主题自带 wowjs 支持,用的是 animate.css + wow.js,给指定 class 的元素加滚动入场动画。
先装插件(它把配置项注册进 Butterfly):
执行位置:博客根目录终端 | 作用:安装 wowjs 插件(wowjs: 配置由它读取并注入页面)。
1 | npm install hexo-butterfly-wowjs --save |
[Blogroot]\_config.butterfly.yml:
文件:[Blogroot]/_config.butterfly.yml | 改法:新增顶层 wowjs: 段;animateitem.class 填元素自身的 class(不带点),想加多个就继续往列表里加 - class/style。
1 | wowjs: |
几个注意点:
animateitem的class填的是元素自身的 class,不用带点;首页卡片就是recent-post-item。- 开了 PJAX 的博客,切页后新内容不会自动重新
new WOW().init()。要么在pjax:complete里手动执行一次,要么只对首页这类会整页重载的页面开动画。 - 三条 CDN 都是
npm.elemecdn.com(国内可直连)。如果哪天访问慢,把三个文件下到source/css、source/js,再改成本地路径即可——和「FontAwesome 图标本地化」那一节是同一套思路。
右键菜单(fomal 版)
原文作者:Fomalhaut(猕猴桃) 链接:https://www.fomal.cc/posts/d739261b.html
自定义右键菜单
默认右键菜单样式比较素,而且手机上长按会误触。换成 fomal 那套:圆形毛玻璃面板、图标 + 文字、滑入动画,顺带把「选择文字后复制/搜索」「粘贴」「回到顶部」「切换昼夜」「阅读模式」「打印」都收进来。
完整实现约 30KB,右键菜单 + 听话鼠标 + 下拉猫猫三合一放在同一个文件里,代码原样贴在下面(收在折叠块里,不需要时不用展开)。
先管放置和注入,代码在后面的代码块里。
把它放到 [Blogroot]\source\js\fomal\cursor.js,然后在 [Blogroot]\_config.butterfly.yml 的 inject.bottom 里排在 jQuery 之后:
文件:[Blogroot]/_config.butterfly.yml | 改法:在 inject.bottom 里把 cursor.js 排在 jquery.min.js 之后;同时把旧的 rightmenu.js、cat.js 两行注释掉,否则两套菜单会叠。
1 | inject: |
原来的 source\js\rightmenu.js、source\js\cat.js 两个注入要注释掉,否则两套菜单叠在一起。
完整 cursor.js(新建 [Blogroot]\source\js\fomal\cursor.js,整段复制进去):
文件:[Blogroot]/source/js/fomal/cursor.js | 改法:新建文件,整段写入;本站 source/js/fomal/cursor.js 已是这份三合一实现,跟着改时用已有文件对照,别新建第二份。
1 | /* ============================================================================ |
菜单项在 cursor.js 的 rightMenuItems 数组里,可以直接改。三项常见修复(都是实际踩过的):
- 回到顶部没反应:主题里
rmf.scrollToTop先取#name-container再删动画 class,非文章页这个节点是null会抛错,后面btf.scrollToDest根本执行不到。加空值保护:
文件:[Blogroot]/source/js/fomal/cursor.js | 改法:在 rmf.scrollToTop() 里用这两行替换原来直接操作 #name-container 的两行(取节点前先判空)。
1 | if (el) el.classList.remove('name-container'); |
- 「美化设置」点了没反应:
[Blogroot]\themes\butterfly\layout\includes\rightmenu.pug里i.fas.fa-cog那两行被//-注释掉了,只剩一个空的<a>。把缩进恢复即可。 - 复制选中内容的链接:菜单里用
rmf.copySelect()即可,选中为空时提前return,否则会复制出一个空字符串。
右侧按钮回到顶部进度
借鉴:Leonus(Fomalhaut 整理)。本站改动:在主题
main.js里改为显示百分比,沿用本站右侧按钮样式。
百分比回顶
点击右下角回到顶部按钮,按钮里显示当前阅读进度百分比(滚到 95% 以上隐藏),滚动时实时更新。
[Blogroot]\themes\butterfly\source\js\main.js 里找到 scrollPercentElement.textContent = scrollPercent:
文件:[Blogroot]/themes/butterfly/source/js/main.js | 改法:找到 scrollPercentElement.textContent = scrollPercent(本站约在第 441 行),按「改后」整行替换;上面两行只是改前改后对照,不要一起粘进去。
1 | // 改前 |
[Blogroot]\themes\butterfly\layout\includes\rightside.pug 的 #go-up 里已经有 <span class="scroll-percent">,不用改结构。
[Blogroot]\source\css\custom.css 追加,让百分比和图标对齐:
文件:[Blogroot]/source/css/custom.css | 改法:追加到文件末尾。
1 | #rightside > div > button > i, |
默认 #go-up 是宽高 35px 的方块,line-height: 35px 让百分比纵向居中;数字用 tabular-nums 更稳(不想加也行,跳动不明显)。
猫猫绳(下拉小猫)
借鉴:tzy 大佬(Fomalhaut 整理)。本站改动:与本站右键菜单合并进同一个
cursor.js,滚动阈值与位置重新调整。
下拉小猫
页面往下滚之后,右上角会垂下来一只小猫(就是那根「猫猫绳」),点它会平滑滚回顶部。
它和右键菜单在同一个文件里([Blogroot]\source\js\fomal\cursor.js),用的是 jQuery 插件的 $.fn.nekoScroll:
文件:[Blogroot]/source/js/fomal/cursor.js | 改法:替换 $(document).ready(...) 里 $('#myscoll').nekoScroll({...}) 的参数;锚点 #myscoll 主题已自带(themes/butterfly/layout/includes/head.pug 里那个空 #myscoll,第 79 行),没有就自己在模板里补一个 <div id="myscoll"></div>。
1 | $('#myscoll').nekoScroll({ |
要点:
- 图片放本地:把小猫图存到
[Blogroot]\source\img\neko.png,nekoImg写/img/neko.png。直接引外链(图床)一旦挂掉,猫就没了。 - 挂载点:需要一个
#myscoll锚点(随便一个空div),猫是插在它旁边的;锚点不存在就不显示。 - 显示时机:
cursor.js里判断#myscoll在视口外、且scrollTop > 0.001时才显示,回到页面顶部自动收起——避免一进首页就挂一只猫在右上角。 - 点击动作:
rmf.scrollToTop(),和右键菜单里的「回到顶部」是同一个函数,所以上一节那个空值保护对它同样有效。
顶部缝隙:APlayer 标记元素把页面顶下去 10px
那条 10px 亮带
现象:导航栏上方有一条 10px 左右、比别处更亮的横带,像遮罩没盖到最顶上。换主题色、调遮罩深浅都没用——因为它根本不是遮罩的问题。
根因:APlayer 初始化时会在 <body> 里塞一个零高度的标记元素:
说明:示意内容,不需要修改——这是 APlayer 初始化后 body 里实际出现的 DOM,用来对照现象。
1 | <div class="aplayer aplayer-tag-marker"></div> |
它是 position: relative; height: 0,但它带着 margin-top: 5px; margin-bottom: 5px。高度为 0 也有 margin,于是把后面所有兄弟元素(#body-wrap、#sidebar、#nav 的定位参照)整体往下推了 10px。
#page-header 从 y=10 开始,而它的 ::before(--mark-bg 那层遮罩)用的是 height: 100%,只会覆盖 header 自身那块区域,顶部这 10px 里露出来的是 #web_bg 的原图,没有遮罩 → 就是那条亮带。
验证方法(不用装任何工具):在本地起服务后,同一个域下建个临时页面,用 iframe 载入首页,读 body.children 的布局:
执行位置:浏览器 F12 控制台(在首页执行)| 作用:打印「高度为 0 却带 margin」的元素,确认那条亮带的来源。
1 | // 简化版:在控制台对首页执行也一样 |
会打印出 aplayer aplayer-tag-marker mt=5px h=0px。再看 #page-header 的 getBoundingClientRect().top 是 10 而不是 0,就坐实了。
修法:把这个标记元素和同源的背景元素全部压成 0,custom.css 加一段
文件:[Blogroot]/source/css/custom.css | 改法:追加到文件末尾。
1 | /* APlayer 注入的零高度标记元素带 5px 上下 margin,会把整页顶下 10px,遮罩就盖不到最顶上 */ |
修完之后 #page-header 的 rect.top 是 0,遮罩与 header 等高,亮带消失。
顺带提醒:判断「遮罩有没有生效」别只看颜色深浅,先量几何——#page-header 的 top 和 ::before 的 height 是否一致,比肉眼靠谱。
统一弹窗:一套卡片 + 最多 5 条
借鉴:Fomalhaut(猕猴桃)。本站改动:把站内三套提示统一到
fomalNotify,最多 5 条并接入美化面板。
把所有提示收进 fomalNotify
站上原本有三套提示各说各话:美化面板用 fomalNotify,性能模式用自己的 toast()(位置在右上、样式也不同),昼夜切换走主题的 Vue $notify / snackbar。同一个站点三种弹窗,看着就很乱。
目标:所有提示都走 [Blogroot]\source\js\fomal\notify.js 里的 fomalNotify(),样式统一、位置统一,并且最多同时在屏幕上留 5 条。
fomalNotify 的调用形式:
说明:调用示例(怎么用),不需要改文件——按这个参数在任意脚本里调 fomalNotify({...}) 就行。
1 | fomalNotify({ |
加 5 条上限:在 notify.js 里维护一个存活列表,创建新卡片前先把超额的关掉。
文件:[Blogroot]/source/js/fomal/notify.js | 改法:在文件顶部(fomalNotify 定义之前)新增这两个声明和 evictOldest() 函数;本站这段已在第 92 行附近。
1 | var MAX_LIVE = 5; |
在 wrap.appendChild(box) 之前调 evictOldest();close() 里要把自己从列表移除,否则列表只增不减:
文件:[Blogroot]/source/js/fomal/notify.js | 改法:在已有的 close()(本站约第 130 行)开头补上「把自己从 live 里移除」这两行,后面的移除动画保持原样。
1 | function close () { |
最后把返回值和入列补上:
文件:[Blogroot]/source/js/fomal/notify.js | 改法:在创建卡片的收尾处换成这三行——先在 wrap.appendChild(box) 之前调 evictOldest(),再 live.push(api) 并返回 api。
1 | var api = { close: close, box: box }; |
暗色适配:卡片本身是浅色底,暗色主题下会白得刺眼,补一段
文件:[Blogroot]/source/css/custom.css | 改法:追加到文件末尾。
1 | [data-theme="dark"] .fomal-notify { background: #252a35; border-color: #3a4150; box-shadow: 0 4px 18px 0 rgba(0, 0, 0, .5); } |
把主题自带的昼夜提示也收过来:themes\butterfly\source\js\sun_moon.js 的 btfNightToast() 最前面加一个优先分支(保留原来的 Vue / snackbar 兜底,主题更新后不至于报错):
文件:[Blogroot]/themes/butterfly/source/js/sun_moon.js | 改法:在 btfNightToast()(本站约第 47 行)函数体最前面插入这段优先分支,原来的 Vue / snackbar 兜底留在后面不要删。
1 | if (typeof window.fomalNotify === 'function') { |
统一位置与时长:把 [Blogroot]\source\js\fomal\perf.js 里的 toast() 从右上角挪到左上角,和面板保持一致
文件:[Blogroot]/source/js/fomal/perf.js | 改法:把 toast() 里 position / offset / duration 三个参数改成下面这行(本站已改成 top-left),上一行只是改前对照。
1 | // 改前:position: 'top-right', offset: 60, duration: 5200 |
验证:控制台连发 6 条带 duration: 60000 的提示,屏幕上应该只剩 5 条,且最早的两条(第 1、2 条)已被淘汰,剩下的是第 2 ~ 6 条;暗色下卡片是 #252a35 深灰底,不是白块。
夜间霓虹灯字
借鉴:Fomalhaut(猕猴桃)。本站改动:配色接本站
CSS变量,浅色模式强制关闭动画。
九色呼吸光晕
思路:浅色模式完全不加动效;暗色模式下给站点标题、副标题、文章信息分别套一条 text-shadow 关键帧动画,让光晕颜色循环流动。
文件:[Blogroot]/source/css/custom.css | 改法:追加到文件末尾。
1 | /* 浅色模式不要任何光晕 */ |
关键帧长这样,0/12.5/25/37.5/43.75/62.5/75/87.5/100% 各一个颜色:
文件:[Blogroot]/source/css/custom.css | 改法:紧接上一段追加;light_10px / light_5px 按注释只改半径,颜色顺序保持一致。
1 | @keyframes light_15px { |
两个容易踩的点:
- 颜色别重复写在同一个百分比:网上流传的版本里
#f1ee47和#b347f1都写在50%,后写的覆盖前写的,黄色实际上永远不出现。要么把黄色挪到43.75%(本文做法),要么删掉一条。 - 小档位的光晕半径要跟着改:
light_5px里漏改一处15px会让光晕在那一瞬间突然膨胀,看着一跳一跳的。
无障碍兜底:系统开了「减少动效」就别闪了
文件:[Blogroot]/source/css/custom.css | 改法:再追加到末尾,放在霓虹灯规则之后。
1 | @media (prefers-reduced-motion: reduce) { |
另外,如果站点开了「性能模式」这类一键降级,不要用 html:not(.perf-lite)[data-theme="dark"] 这种前缀把它排除掉——两个元素的 text-shadow 动画几乎不花性能,但一旦被排除,很多人会开着性能模式却看不到效果,以为是没生效。
Hexo 8 / Butterfly 5.7.2 配置清单
大版本升级迁移
在 [Blogroot]\package.json 添加:
文件:[Blogroot]/package.json | 改法:在顶层对象里加 "engines" 键(这是一段对象片段,插进去时注意和前一项之间的逗号)。
1 | "engines": { "node": ">=20.19.0" } |
执行:
执行位置:博客根目录终端 | 作用:把 Hexo 固定到 8.1.2,然后清缓存重新生成,确认主题在新版本下能编过。
1 | npm install hexo@8.1.2 --save-exact |
[Blogroot]\_config.butterfly.yml 配置键映射:
| 4.x | 5.x |
| —- | —- |
| local_search.enable: true | search.use: local_search |
| fancybox: true / medium_zoom | lightbox: fancybox |
| mathjax.enable: true | math.use: mathjax |
| sharejs.enable: true | share.use: sharejs |
| highlight_theme 等 6 个键 | code_blocks.theme / macStyle / copy / language / shrink / height_limit / word_wrap / fullpage |
| footer_bg | footer_img |
| footer.copyright: false | footer.copyright: { enable: false, version: false } |
| footer_beautify 徽标文案 | Hexo_v8.1.2 / Butterfly_v5.7.2 |
连字符键改成下划线键:
| 4.x | 5.x |
| —- | —- |
| font.global-font-size | font.global_font_size |
| font.code-font-size | font.code_font_size |
| font.font-family | font.font_family |
| font.code-font-family | font.code_font_family |
| beautify.title-prefix-icon | beautify.title_prefix_icon |
| beautify.title-prefix-icon-color | beautify.title_prefix_icon_color |
| hr_icon.icon-top | hr_icon.icon_top |
background 只填纯路径:
文件:[Blogroot]/_config.butterfly.yml | 改法:顶层 background: 只填纯路径,不要写 url(...),也不要带引号里的括号。
1 | background: /img/bg.webp |
[Blogroot]\themes\butterfly\layout\includes\layout.pug 补 #footer-wrap:
文件:[Blogroot]/themes/butterfly/layout/includes/layout.pug | 改法:核对 footer#footer 下是否有这两层;5.7.2 已自带,只是确认,不要重复添加。
1 | footer#footer(style=footer_bg) |
[Blogroot]\themes\butterfly\layout\includes\layout.pug 删掉 4.x 手加的 third-party/search/index 那行。
模板判断改成:
文件:主题模板里 4.x 写成 if page.type === 'post' / is_post() 的那类判断(例如 themes/butterfly/layout/includes/header/nav.pug:8)| 改法:把条件换成 if globalPageType === 'post'。
1 | if globalPageType === 'post' |
文件:[Blogroot]/themes/butterfly/layout/page.pug(本站约第 13 行)| 改法:把页面标题的判断换成这两行,只有 top_img === false 的页面才渲染 h1.page-title。
1 | if top_img === false && page.type != 'music' && page.title |
[Blogroot]\themes\butterfly\source\js\sun_moon.js 用 btf.activateDarkMode() / btf.activateLightMode() / btf.saveToLocal.set('theme', mode, 2),代码见第二章第 11 项。[Blogroot]\source\css\custom.css 追加 5.x 双排适配,代码见本章第 28 项。
保持不动的挂载点:#recent-posts、.sticky_layout、.recent-post-item。
生成后检查:
执行位置:博客根目录终端 | 作用:清缓存重新生成,下一步去 public/ 里核对注入结果。
1 | hexo clean && hexo g |
在 public/index.html 中确认存在:footer-wrap、beian-row、rightMenu、main-hero-waves-area、loading-image-dot、recent-post-items。
改完怎么验证与部署
改完不要直接往服务器扔,按顺序走一遍,出错能马上定位在哪一步:
- 生成。博客根目录终端执行
hexo generate。命令跑完没报FATAL才算过,public/里会重新产出整站。 - 本地预览。
hexo server(默认http://localhost:4000,端口被占就hexo s -p 4001)。逐节点开对应页面:首页看磁贴、轮播、多栏和侧栏卡片,文章页看备案、右键菜单、猫猫绳和 FPS 药丸,评论页发一条测试评论。 - 强制刷新 / 清缓存。改过
source/css/、source/js/的话,把_config.butterfly.yml里inject对应行的?v=xxx版本号改一版(如?v=20261111a换成?v=20261111b),再 Ctrl+F5 或开无痕窗口看;还不行就删掉public/、.deletions和浏览器里该站点的 Service Worker 缓存后重新生成。 - F12 查 404。Network 面板勾上
404过滤、刷新一次,重点看/css/custom.css、/js/fomal/*.js、/css/brinks.css、/font/*.woff2、/webfonts/*、/img/*有没有红条——这些基本都是路径写错或文件没放进去。再看 Console,fomalNotify、Cursor、fpsSwitch之类报undefined说明脚本没注入或顺序不对(脚本要排在 jQuery 之后)。 - 按原托管方式上传。Nginx / 宝塔:把
public/整个传上去;GitHub Pages:用_config.yml里的deploy: type: git再hexo deploy;Vercel / Netlify:把仓库推上去,构建命令hexo generate、输出目录public,让它自动构建。上线后再强刷一次,确认线上版本号就是刚改的那版。
这篇已经把第 21 ~ 41 个魔改写完了,18544 字、阅读约 89 分钟,再往下堆就不好翻了。
后面新的魔改我会单独开一篇《hexo魔改教程(四)》,本篇不再追加——想跟更新的部分,从系列导航里找(四)就行。
