综合美化模块教程:一个面板管完整站外观
博客搭建与魔改系列教程导航🚥🚥🚥
这一篇单独讲「综合美化模块」:把主题色、卡片透明度、字体、壁纸、布局和特效收进一个弹窗面板,改完即时生效,刷新后保持。适用 Hexo 8.1.2 + Butterfly 5.7.2。
借鉴:Fomalhaut(猕猴桃)。本站改动:面板结构、
CSS变量、持久化与动画降级按本站实现重写,不是原样搬运。
阅读约定:每个代码块上方都标了 文件 与 改法。[Blogroot] 指博客根目录;「新建」是建好文件后整段写入,「追加」是放到文件末尾,「在已有文件的某函数内补全」是在本站已有的同名脚本里改对应位置,不要另建一份。面板外观类样式放 source/css/beauty-panel.css,卡片底色、字号、圆角这类全局魔改放 source/css/custom.css,两者不要混。
综合美化模块到底做了什么
一般的主题换肤,要么改 _config 重新生成,要么在浏览器里用开发者工具临时改两下。综合美化模块把这两件事合在一起:
- 入口固定:导航栏一个调色盘按钮,右键菜单里也能打开同一个面板。
- 即时预览:拖滑块、点色点、换字体,页面立刻变化,不刷新。
- 持久保存:偏好写进
localStorage,下次打开还是你调好的样子。 - 互不打架:所有外观都收口到一组 CSS 变量和
<html>上的类名,主题源码一行不用改。
它不是一个单独的插件,而是「一个首屏脚本 + 一份样式 + 一个面板脚本 + 几组特效脚本」拼起来的模块。下面按这个顺序讲,每一步都写明改哪个文件。
开始之前:文件与加载顺序
文件清单
整套模块按职责拆成这些文件,路径都在博客根目录 [Blogroot] 下:
| 文件 | 职责 |
|---|---|
source/js/fomal/boot.js | 首屏同步脚本,读 localStorage 并写 CSS 变量,防止刷新闪烁 |
source/js/fomal/winbox.min.js | 弹窗组件 WinBox,提供可拖动、可最小化的面板外壳 |
source/js/fomal/notify.js | 轻提示,面板操作后的「已切换」小弹窗 |
source/js/fomal/fonts.js | 字体选择、字体加载检测 |
source/js/fomal/backgrounds.js | 壁纸、纯色、自定义链接三种背景 |
source/js/fomal/snow.js | 落雪(Canvas) |
source/js/fomal/fireflies.js | 萤火虫微光(纯 CSS 动画) |
source/js/fomal/ripple.js | 点击涟漪 |
source/js/fomal/panel.js | 面板本体:HTML、分组、交互、恢复默认 |
source/css/beauty-panel.css | 面板皮肤 + 外观开关 + 变量落点 |
source/css/custom.css | 主题色变量、卡片底色、圆角、字体基准等全局规则 |
加载顺序很重要,先记住一句话:首屏脚本同步放 head,其余依赖放 bottom 且保持「底层能力 → 面板」的先后。
一、设计思路:首屏同步 + CSS 变量 + 单一数据源
三层结构
综合美化模块分成三层,各管一件事:
- 数据层:
localStorage。所有偏好只存一份,键名统一在boot.js里声明。 - 应用层:
boot.js在<head>里同步执行,把偏好翻译成 CSS 变量和<html>类名。 - 交互层:
panel.js只负责面板渲染和事件,改完值后同时「立即改样式 + 写回localStorage」。
boot.js 必须是同步脚本,不能加 defer。它要在浏览器绘制第一帧之前就把变量写好,否则会先闪一下默认蓝色、默认字体,再跳成你的配置。
先看键名和默认值的写法:
文件:[Blogroot]/source/js/fomal/boot.js | 改法:在已有文件的 DEFAULTS 和 KEYS 两个对象里补全,新增一项要两处同时加;从零接入时先新建该文件,再整段写入。
1 | var DEFAULTS = { |
键名集中管理的好处是:boot.js、panel.js、特效脚本都引用同一张表,以后改名只改一处。
然后一次性把变量写进 <html>:
文件:[Blogroot]/source/js/fomal/boot.js | 改法:在已有文件 IIFE 末尾的「应用偏好」段补全(var d = w.document.documentElement 之后),位置必须在 HGBeauty.read() 之后。
1 | var d = document.documentElement |
这里有两个原则:
- 能用变量就不用类名:颜色、透明度、字号、圆角都是变量,改一个值全站生效。
- 只有「整块显隐 / 布局反转」才用类名:例如侧栏隐藏、侧栏换边、顶栏常驻。
read() 里所有数值都要做一次范围校验,避免用户手动改 localStorage 后把页面搞坏:
文件:[Blogroot]/source/js/fomal/boot.js | 改法:在已有文件 HGBeauty.read() 返回的对象里替换 opacity、theme 两行,其余键照同样写法补范围校验。
1 | opacity: num(get(KEYS.opacity, DEFAULTS.opacity), DEFAULTS.opacity, 0, 100), |
二、弹窗骨架:把面板装进 WinBox
创建面板
WinBox 是一个无依赖的浮动窗口库,自带拖动、最大化、最小化和关闭。面板的创建代码放在 panel.js:
文件:[Blogroot]/source/js/fomal/panel.js | 改法:在已有文件的 toggleWinbox() 函数内补全「创建面板」分支。
1 | winbox = window.WinBox({ |
几个细节值得单独说:
background: 'var(--theme-color)'让标题栏跟随主题色,换色后不用重建窗口。- 尺寸先用
panelSize()根据视口算,再夹在安全范围里,手机上面板不会超出屏幕。 - WinBox 原生的最小化是「贴到屏幕左下角」。这里在
onminimize里再挪一次,让它在水平和垂直方向都居中:
文件:[Blogroot]/source/js/fomal/panel.js | 改法:在已有文件的 centerMinimized() 函数内补全,位置紧跟在 toggleWinbox() 之后。
1 | function centerMinimized (box) { |
最小化后窗口高度只剩标题栏(约 35px),所以直接用 offsetHeight 算垂直居中即可。setTimeout(..., 0) 是为了等 WinBox 把 min 类和高度都应用完再量尺寸。窗口大小变化时,如果仍处于最小化状态,也要重新居中:
文件:[Blogroot]/source/js/fomal/panel.js | 改法:在已有文件的 resize() 函数内补全,紧接 centerMinimized() 定义之后。
1 | function resize () { |
最后把入口挂到 window 上,Pug 模板里就能直接写 onclick="toggleWinbox()":
文件:[Blogroot]/source/js/fomal/panel.js | 改法:追加到已有文件末尾的导出段(和 w.HG_PANEL 等导出写在一起),只加这一行。
1 | window.toggleWinbox = toggleWinbox |
两个入口按钮
导航栏按钮改 [Blogroot]\themes\butterfly\layout\includes\header\nav.pug,加在菜单和昼夜按钮之间:
文件:[Blogroot]/themes/butterfly/layout/includes/header/nav.pug | 改法:在已有文件的菜单项与昼夜切换按钮之间插入(和相邻 a 同级缩进两格);这是主题源码,升级主题会被覆盖,改完记得备份。
1 | //- 美化设置 |
图标可以换成任意 Font Awesome 图标,也可以内联 SVG。导航栏的悬停效果沿用站点自己的 .faa-tada 动效即可,不必再写一套。
右键菜单改 [Blogroot]\themes\butterfly\layout\includes\rightmenu.pug:
文件:[Blogroot]/themes/butterfly/layout/includes/rightmenu.pug | 改法:在已有文件的右键菜单项列表里插入一条,缩进和相邻 a.rightMenu-item 一致。
1 | a.rightMenu-item(href="javascript:toggleWinbox();") |
同一个 toggleWinbox() 会处理三种情况:没开就创建,已开就关闭,最小化状态先恢复。
面板分组
面板内容由 panelHTML() 一次性拼好,再塞进 winbox.body。目前分这几组:
- 显示偏好:卡片不透明度、背景滤镜开关、模糊 / 饱和度 / 对比度。
- 氛围特效:星空、霓虹、雪花、萤火虫、昼夜过场档位。
- 互动挂件:猫咪、听话鼠标、帧率监测、点击涟漪、性能模式。
- 布局与部件:右侧部件、顶栏常驻、侧栏显示、右侧图标颜色、侧栏位置。
- 主题色:11 个预设色点 + 自定义取色器。
- 字体:正文 / 代码字体、整站字号、卡片圆角。
- 背景:壁纸、纯色、自定义 HTTPS 链接。
每个开关都是「标签 + 说明小字 + 胶囊开关」的固定结构,统一由 toggleRow() 生成,减少重复 HTML:
文件:[Blogroot]/source/js/fomal/panel.js | 改法:在已有文件的 toggleRow() 函数内补全(面板 HTML 拼装区)。
1 | function toggleRow (id, title, note, checked, handler) { |
三、主题色:一次改一组变量
预设色与派生色
主题色不是只改一个 --theme-color。主题里链接悬停、按钮、分页、滚动条、选中背景都引用了不同变量,所以 applyTheme() 要一次写全:
文件:[Blogroot]/source/js/fomal/panel.js | 改法:在已有文件的 applyTheme() 函数内补全写变量的部分,--on-theme 用 B.ink(rgb) 取值。
1 | function applyTheme (hex) { |
mix() 把主题色和白色按比例混合,得到按钮悬停色;ink() 根据亮度决定「实底上的文字」用黑还是白:
文件:[Blogroot]/source/js/fomal/boot.js | 改法:在已有文件的 ink() 函数内补全,并确认它已挂到 HGBeauty.ink;panel.js 只调用,不要另写一份。
1 | function ink (rgb) { |
这样选浅黄、浅粉主题色时,按钮文字自动变深,不会白字糊成一片。
预设色定义在 panel.js 顶部,想加自己的颜色只需要多写一行:
文件:[Blogroot]/source/js/fomal/panel.js | 改法:在已有文件顶部的 PRESETS 数组里追加一项,id 不要和已有色点重复。
1 | var PRESETS = [ |
主题里写死的颜色怎么办
主题有些地方把颜色写死了,变量覆盖不到,需要在 [Blogroot]\source\css\beauty-panel.css 里单独接一次。典型的是文章目录高亮(主题默认固定为青色)和作者卡的「前往小家」按钮:
文件:[Blogroot]/source/css/beauty-panel.css | 改法:追加到文件末尾;主题色相关的面板样式统一放这里,不要写进 custom.css。
1 | /* 目录高亮跟随主题色 */ |
判断标准很简单:背景用 --theme-color,实底上的文字用 --on-theme。不要再写死 #fff,否则换浅色主题时会看不清。
四、卡片不透明度与背景滤镜
不透明度
滑块和数字框绑定同一个值,范围 0–100,默认 88:
文件:[Blogroot]/source/js/fomal/panel.js | 改法:在已有文件的 setOpacity() 函数内补全。
1 | function setOpacity (value, persist) { |
真正让滑块生效的是 CSS 里所有卡片都引用这两个变量。Butterfly 5.x 的首页在 #recent-posts 和文章卡之间多了一层 .recent-post-items,旧选择器只写直接子元素会漏掉首页卡片:
文件:[Blogroot]/source/css/custom.css | 改法:追加到文件末尾;卡片底色属于通用魔改,放 custom.css 而不是 beauty-panel.css。
1 | #recent-posts > .recent-post-item, |
分页那一排也吃同一个变量。注意主题的 .pagination > *:not(.space) 把省略号排除在卡片底之外,不补的话「…」是一块透明的空白:
文件:[Blogroot]/source/css/custom.css | 改法:紧接上一段卡片底色规则追加,继续留在 custom.css。
1 | #pagination .pagination .page-number, |
滑块调到 100% 是纯实底,调到 0% 完全透明。如果觉得毛玻璃太重,可以把 backdrop-filter 一并做成变量,或交给低性能模式统一降级。
背景滤镜
滤镜只作用在背景层 #web_bg,不影响正文卡片:
文件:[Blogroot]/source/js/fomal/panel.js | 改法:在已有文件的 paintFilter() 函数内补全,替换其中写变量、加类名的几行。
1 | root.style.setProperty('--hg-bg-filter', |
文件:[Blogroot]/source/css/beauty-panel.css | 改法:追加到文件末尾的背景图规则区(html.hg-has-bg #web_bg 附近)。
1 | #web_bg { |
这里踩过一个坑:一开始只要开启滤镜就 scale(1.03),于是「模糊值调到 0」时背景图仍被放大,看起来像莫名其妙裁掉了一圈。正确做法是把「是否模糊」和「是否开启滤镜」拆成两个类名,blur > 0 才加 hg-bg-blurred。
五、字体、字号与圆角
字体选择
正文和代码字体分成两组。正文按用途再分「阅读」和「装饰」,面板里用小标题隔开:
文件:[Blogroot]/source/js/fomal/fonts.js | 改法:在已有文件顶部的 TEXT_FONTS / CODE_FONTS 两个数组里补全,group 决定它落在「阅读」还是「装饰」小标题下。
1 | var TEXT_FONTS = [ |
选中后只改一个变量,CSS 负责落到具体元素:
文件:[Blogroot]/source/js/fomal/fonts.js | 改法:在已有文件的 apply() 函数内补全(先设变量,再写 localStorage)。
1 | document.documentElement.style.setProperty('--hg-text-font', textStack(key)) |
文件:[Blogroot]/source/css/beauty-panel.css | 改法:追加到文件末尾的字体区,和顶部 @font-face 放在同一段。
1 | body { |
本地字体在 beauty-panel.css 顶部用 @font-face 引入,font-display: swap 保证字体没加载完时先用回退字体显示,不出现空白。
字体加载检测的两个坑
面板需要判断「这个字体到底有没有加载成功」,但 document.fonts.load() 对系统字体经常返回空结果。这里做了两件事:
文件:[Blogroot]/source/js/fomal/fonts.js | 改法:SYSTEM 白名单放在已有文件顶部的常量区,load() 在已有文件里替换同名函数。
1 | /* Consolas、Monaco 和系统默认字体不检测,直接算可用 */ |
- 系统字体白名单:
Consolas在本机明明能用,但fonts.load可能返回空数组,误报「加载失败」。直接跳过检测最稳。 - 超时兜底:网络慢时不能无限转圈,9 秒判失败并保留原字体。
如果字体文件路径写错,控制台会报 404,这种才是真的加载失败。
字号与圆角
「标准 / 大」两档对应 1 和 1.15 两个倍数。注意主题把基准字号写在 body 上,只改 <html> 的 font-size 不会生效,要直接缩放 body:
文件:[Blogroot]/source/css/custom.css | 改法:追加到文件末尾;字号基准属于通用魔改,放 custom.css,不要写进 beauty-panel.css。
1 | :root { |
这样正文、评论、目录里所有用 em 的子元素会一起缩放,比逐个选择器改字号稳。
圆角三档对应 6px / 12px / 18px,落在卡片、分页、版权框和代码块上。分页里的省略号 .space 也要带上,否则它是个直角白块:
文件:[Blogroot]/source/css/custom.css | 改法:紧接上一段字号规则追加,圆角和字号放在同一处。
1 | .card-widget, |
六、背景设置:壁纸、纯色、自定义链接
三种背景
背景面板分三个页签:
- 壁纸:二次元、风景、萌宠、手机四个分类,点击缩略图切换。
- 颜色:预设纯色 + 自定义取色器。
- 自定义:粘贴一个 HTTPS 图片链接,先预览验证,再应用到全站。
所有远程图片都先探测再应用,加载失败就保留当前背景,不会把页面搞成一片空白:
文件:[Blogroot]/source/js/fomal/backgrounds.js | 改法:在已有文件的 probe() 函数内补全,替换图片探测的 onload / onerror 回调。
1 | var image = new Image() |
应用时只做两件事:写变量、加类名。
文件:[Blogroot]/source/js/fomal/backgrounds.js | 改法:在已有文件的 apply() 函数内补全,写变量和加类名都在这一处。
1 | function apply (value) { |
文件:[Blogroot]/source/css/beauty-panel.css | 改法:追加到文件末尾的背景图规则区。
1 | html.hg-has-bg #web_bg { |
这里必须用 !important:主题会给 #web_bg 写内联 background-image,手机端还有一条带 !important 的规则,普通选择器压不过去。
教程里的示例图用了公共占位图服务,正式使用时换成自己的图片,建议压缩成 WebP 并放在本地 source/img 下,既快又不依赖第三方。
自定义链接与配置格式
「自定义」页签只接受 https:// 开头的图片链接,取色器也只接受十六进制颜色。校验放在应用前,而不是等 CSS 渲染失败:
文件:[Blogroot]/source/js/fomal/boot.js | 改法:在已有文件的 bgToCss() 函数内补全,并确认已导出到 HGBeauty.bgToCss;backgrounds.js 里只调用,不重复实现。
1 | function bgToCss (value) { |
如果你同时把壁纸写进主题配置,注意 Butterfly 5.x 的 background 只填纯路径或颜色,例如 background: /img/bg.webp。5.x 会自动包一层 url(),你再手写 url(...) 就会变成双层 url(),最终背景 404、首页空白。综合美化模块内部存的是 url(...),所以它自己负责用 bgToCss() 转换,两套逻辑不要混用。
七、布局与部件
侧栏换边、顶栏常驻、右侧部件
这三项都是「加一个类名,让 CSS 换一种布局」,不动主题的 Pug 结构。
侧栏从右换到左,本质是把同一行 flex 反向排列:
文件:[Blogroot]/source/css/beauty-panel.css | 改法:追加到文件末尾的布局开关区,hg-aside-left 系列规则放一起。
1 | html.hg-aside-left #content-inner.layout { |
但主题只给「侧栏在右」留了 padding-left: 15px。反排到左侧后,这段空白跑到最外边,侧栏和文章就贴在一起了。所以要把内边距换到另一边:
文件:[Blogroot]/source/css/beauty-panel.css | 改法:紧接上一段 hg-aside-left 规则追加,媒体查询里的内边距修正要和它连着写。
1 | @media (min-width: 900px) { |
顶栏常驻则是把主题滚动时的 top: -60px 和上滑位移一起取消:
文件:[Blogroot]/source/css/beauty-panel.css | 改法:追加到文件末尾,hg-nav-always 单独一组。
1 | html.hg-nav-always #page-header.nav-fixed #nav { |
右侧部件隐藏最简单,直接不显示:
文件:[Blogroot]/source/css/beauty-panel.css | 改法:追加到文件末尾,紧跟 hg-nav-always 那组。
1 | html.hg-rightside-off #rightside { |
右侧图标颜色与一个全局覆盖的坑
右侧「回到顶部 / 目录」等按钮默认是白色。为了让颜色可配置,用了一个专用变量:
文件:[Blogroot]/source/css/custom.css | 改法:追加到文件末尾;这条右侧图标颜色规则实际写在 custom.css,不在 beauty-panel.css。
1 | #rightside > div > button, |
文件:[Blogroot]/source/js/fomal/panel.js | 改法:在已有文件的 setRightsideColor() 函数内补全。
1 | function setRightsideColor (value, persist) { |
这里有个很容易犯的错:不要为了「让按钮跟随主题色」去写全局的 --btn-color: var(--on-theme) !important。主题的 --btn-color 被大量按钮共用,一改就会把右侧图标、播放器按钮、各种圆形按钮全部变深,看起来像图标「变黑」了。正确做法是只给目标区域一个专用变量,默认值保持白色。
八、特效开关:默认值、互斥与降级
雪花
雪花用 Canvas 绘制,核心是「预渲染雪片 + 时间驱动 + 有限高度积雪」:
- 雪片不是每帧重新画路径,而是预先渲染两种尺寸的六臂雪片贴图,帧里只做
drawImage。 - 位置按时间差推进,切后台再回来不会瞬移。
- 落地后在底部累积一层薄雪,并给新雪片留出空间。
- 只在浅色、桌面端(宽度 > 768px)且系统没有要求减少动态效果时运行。
- 页面隐藏、
pagehide、系统开启prefers-reduced-motion时自动停掉绘制循环。
文件:[Blogroot]/source/js/fomal/snow.js | 改法:在已有文件的 frame() 函数内补全,落地积雪与重置雪片写在绘制之后。
1 | function frame (time) { |
默认开启,但只在白天桌面生效;夜间、手机和「减少动态效果」偏好下会自动隐藏,不需要用户额外操作。
萤火虫、涟漪与互斥
萤火虫是纯 CSS 动画,没有 Canvas、没有 requestAnimationFrame、没有常驻定时器:
- 桌面 14 个、窄屏 8 个光点,随机分布在下半屏。
- 每个光点独立设置漂移时长、呼吸时长、延迟和颜色,靠 CSS 变量驱动。
- 页面隐藏时给容器加
hidden,动画暂停。
雪花和萤火虫互斥:两者都在背景层,同时开会糊成一片。开启萤火虫时自动关掉雪花,开启雪花时自动关掉萤火虫:
文件:[Blogroot]/source/js/fomal/panel.js | 改法:在已有文件的 setSnow() 函数里补全这段互斥;反向的「开萤火虫时关雪花」在 [Blogroot]/source/js/fomal/fireflies.js 的启用逻辑里(snowOn() 成立时调 disableSnow()),两处都要有。
1 | // 雪花开启时 |
点击涟漪默认开启,按下位置泛开两圈水纹,700ms 后自动移除。最多同时保留 6 组,关闭时连 pointerdown 监听都不挂:
文件:[Blogroot]/source/js/fomal/ripple.js | 改法:在已有文件的 spawn() 函数内补全。
1 | function spawn (x, y) { |
prefers-reduced-motion 打开时,涟漪和萤火虫都会暂停,而不是直接报错或继续播放。
星空、霓虹与挂件
星空和霓虹沿用主题已有的 Canvas 和动画,面板只负责显示 / 隐藏:
文件:[Blogroot]/source/css/beauty-panel.css | 改法:追加到文件末尾,星空与霓虹两个开关放同一组。
1 | html.hg-universe-off #universe { |
主题的星空脚本每帧都会检查 Canvas 是否可见,display: none 后绘制循环会自己停掉,不需要改它的源码。
猫咪挂件、听话鼠标、帧率监测、性能模式由已有脚本提供开关函数,面板只调用:
文件:[Blogroot]/source/js/fomal/panel.js | 改法:分别补在已有文件的 setNeko()、setCursor()、setFps()、setPerf() 四个函数里,每个函数只留对应那一行。
1 | if (typeof window.setNekoEnabled === 'function') window.setNekoEnabled(true) |
这体现了一个原则:面板不重复实现能力,只做开关和持久化。以后新增特效,只要对方暴露一个 setEnabled(),面板加一行调用即可。
九、恢复默认与刷新后的状态
一键恢复
「恢复默认设置」不是逐个手写重置,而是遍历默认值表:
文件:[Blogroot]/source/js/fomal/panel.js | 改法:在已有文件的 resetAll() 函数内补全,新增配置项后这里不用改。
1 | function resetAll () { |
好处是新增配置项时,只要往 DEFAULTS 和 KEYS 里各加一行,重置逻辑自动覆盖,不会漏项。
刷新后的状态由 boot.js 负责恢复。由于所有脚本是整站注入、不是每次切换页面都重新执行,Pjax 跳转后变量和 <html> 类名仍然在,面板打开时的控件状态则由 syncAll() 从 localStorage 重新读取。
十、接入步骤与避坑清单
五步接入
- 放文件:把
boot.js、panel.js、fonts.js、backgrounds.js、snow.js、fireflies.js、ripple.js、winbox.min.js放进[Blogroot]\source\js\fomal\;把beauty-panel.css放进[Blogroot]\source\css\。 - 注入资源:改
[Blogroot]\_config.butterfly.yml的inject,注意boot.js同步放head,其余按依赖顺序放bottom。 - 加入口:改
nav.pug和rightmenu.pug,两处都调用toggleWinbox()。 - 补全局样式:在
custom.css里补--hg-font、--hg-radius和卡片底色规则;主题色、目录高亮、右侧图标等写死颜色的地方按前面的方式接到变量上。 - 本地验证:
npx hexo generate后打开页面,逐项拖动滑块、切换字体和壁纸,再刷新确认状态保持。
配置参考(版本号和你的实际文件保持一致即可):
文件:[Blogroot]/_config.butterfly.yml | 改法:并进已有的 inject 配置,boot.js 放在 inject.head 列表里且不加 defer,其余按顺序放进 inject.bottom 列表;已有同名资源就改原行,不要重复添加。
1 | inject: |
为什么顺序不能乱:panel.js 在创建面板时要读取 HGBeauty、HG_FONTS、HG_BACKGROUNDS,还要给雪花、萤火虫、涟漪挂开关;这些都必须在它之前加载。WinBox 也必须比 panel.js 先到,否则面板创建时会提示「弹窗组件没加载成功」。
避坑清单
boot.js不要加defer:它必须在首帧前执行,否则刷新会闪默认样式。- Butterfly 5.x 首页多了一层
.recent-post-items:卡片透明度、双排布局等选择器都要同时匹配两层。 - 不要全局覆盖
--btn-color:会让右侧图标和大量圆形按钮一起变深,应使用--hg-rightside-color这类专用变量。 - 模糊值 0 不要放大背景:
hg-bg-filtered和hg-bg-blurred分开判断,只有blur > 0才执行scale。 - 系统字体直接放行:
Consolas、Monaco、系统默认字体不要交给document.fonts.load()判断,避免误报加载失败。 - 字号改
body,不要改html:主题把基准字号写在body上,改<html>没有效果。 - 主题配置里的背景只写路径:Butterfly 5.x 会自动包
url(),手写url(...)会变成双层。 - 键名集中管理:
boot.js、panel.js和特效脚本共用同一张键名表,改名要一起改。 - 最小化居中要等一帧:WinBox 先在回调里贴左下,
setTimeout(..., 0)后再按实际标题栏高度计算居中位置。 - 改完配置文件强刷:
?v=参数用来打破缓存;如果预览没变化,重启hexo server再强制刷新一次。
最后提醒一句:面板的价值在于「收口」。新增任何外观项,都先问自己能不能变成一个 CSS 变量或一个 <html> 类名;能的话,面板只需要加一个控件和一次 setProperty(),不要再写一套独立逻辑。
小结
综合美化模块的核心只有三句话:首屏同步应用偏好,所有外观走 CSS 变量和类名,面板只负责交互与持久化。按这篇文章的顺序接入,你可以得到一个即时生效、刷新保持、移动端也不会挤爆的美化面板。
下一步,打开面板把主题色调成你喜欢的颜色,再切换一次正文字体——这两项最能立刻看出模块是否接对了。
延伸:列表页短内容的展开卡片
列表页文章不足时,网站信息、公告、欢迎来访、倒计时和那年今日会进入 #hg-side-fill 的整页全宽网格。这部分没有新增面板控件,颜色、圆角和卡片底色继续吃美化面板的 CSS 变量;容器上的 hg-fill-has-welcome、hg-fill-has-countdown 只负责布局分栏,不是新的持久化偏好。
卡片搬出侧栏后要把 20px 24px 内边距一起补上,否则标题会贴边;这类规则和颜色变量一样都落在 custom.css。完整测量、搬运、逐张回收和 pjax 恢复逻辑在 hexo魔改教程(六),本节不重复代码。
改完怎么验证与部署
文件放好、inject 顺序也对齐之后,不要直接上传,先按这个顺序走一遍:
- 生成:在博客根目录执行
hexo generate,命令行出现Generated再往下走。这一步报错,九成是_config.butterfly.yml的inject列表缩进或路径写错,先修配置再看别的。 - 本地预览:执行
hexo server,打开http://localhost:4000。打开面板依次试主题色、卡片不透明度、正文字体、壁纸和各特效,然后刷新一次,确认boot.js把偏好恢复回来、首帧不闪默认蓝色(闪一下说明它被加了defer或没放head)。 - 强刷或清缓存:改过
custom.css、beauty-panel.css或fomal下的脚本后按Ctrl + F5;_config.butterfly.yml里对应的?v=版本号也要升一次,没升就改完重启hexo server。启用了 Service Worker 时,再到 DevTools → Application → Service Workers 点Update或Unregister。 - F12 查 404:Console 不应出现
boot.js、panel.js、beauty-panel.css、winbox.min.js之类 404;Network 里筛fomal和beauty-panel,确认请求全部 200 且版本号是刚改的。面板弹出「弹窗组件没加载成功」,说明winbox.min.js没排在panel.js之前。 - 上传
public/:生成目录就是public/,按原来的托管方式传上去——Nginx 直接把public/覆盖到站点根目录,GitHub Pages 推送到发布分支或用 GitHub Actions,Vercel 连仓库自动构建,本地脚本托管则hexo deploy。上线后关掉缓存再访问一次,确认线上与本地一致。
如果线上和本地不一致,先怀疑缓存而不是代码:?v= 参数、Service Worker 缓存、CDN 缓存三层里任意一层没更新,看起来都像「改了没生效」。
