字体管理（Halo-plugin-fonts）

源码仓库：https://github.com/MyrStar/Halo-plugin-fonts
作者：Eternal

一款 Halo 2.x 插件，提供全站字体的可视化管理能力：后台在线预览与切换字体、配置 CDN 加速地址、按字体独立调整字重，前台访客还可通过浮窗自由切换字体。

功能特性

• 🎨 字体管理页面：卡片式实时预览（可自定义预览文本），启用/停用、设为默认、编辑、删除
• 📦 内置预设库：12 款免费可商用字体开箱即用（思源黑体/宋体、霞鹜文楷、站酷系列等）
• 🛒 推荐字体库：12 款来自 cn-fontsource（中文网字计划）与 npm CDN 的精选字体（得意黑、MiSans、阿里妈妈东方大楷、钉钉进步体等），一键添加为可自由编辑的自定义字体
• ✍️ 自定义字体：填入 font-family 与字体 CSS 地址即可接入任意 Web 字体
• ⚖️ 按字体独立字重：每款字体可单独设置 400/500/600/700，解决偏细字体看不清的问题
• 🚀 字体加速地址：对字体 CSS 地址做主机映射替换（如 googleapis → loli.net、jsdelivr → fastly）
• 🪟 前台切换浮窗：访客选择记忆在浏览器 localStorage，支持四个角落位置与自定义提示文字
• 🎯 精细作用范围：可配置字体作用的 CSS 选择器，避免污染代码块等宽字体
• 🍃 按需加载：仅注入已启用字体的 CSS，中文 Web 字体按 unicode-range 分包，首屏只下载实际用到的分片

实现原理

• 字体列表存储在插件 ConfigMap 中，通过 ReactiveSettingFetcher 实时读取，保存即生效，无需重启
• 后端通过 TemplateHeadProcessor 向前台 <head> 注入字体 CSS <link> 与覆盖样式：以 CSS 变量承载当前字体族，配合 :where() 低特异性 + !important，既能压过主题普通规则，又允许主题带 !important 的规则覆盖插件
• 加速规则仅做 CSS 入口主机替换（镜像站需会改写 CSS 内部字体文件地址，如 loli.net 系镜像），插件不抓取任何远端内容
• 前台浮窗为无依赖原生 JS，通过插件公开 API 获取已启用字体；切换时动态更新覆盖规则，访客选择存入 localStorage

安装

1. 在 Releases 下载最新的 plugin-fonts-x.y.z.jar
2. Halo 后台 → 插件 → 安装 → 上传 jar 并启用
3. 左侧菜单「界面」分组下点击「字体管理」即可使用

要求 Halo >= 2.22。

使用

• 添加字体：「从预设库添加」弹窗分「内置预设 / 推荐字体」两个页签，悬停卡片即可加载真实字体预览；也可以手动添加自定义字体
• 设为默认：全站默认使用该字体；「恢复跟随主题」则不覆盖主题字体
• 字重：编辑任意字体可设置字重，仅作用于该字体；单字重字体设置更高字重时由浏览器合成加粗
• 加速规则：插件设置页中配置，可增删多条并单独启停
• 前台浮窗：访客点击悬浮按钮（默认右下角「Aa」）即可在「站点默认」与所有已启用字体间切换

注意：字体作用选择器每行一个 CSS 选择器，默认 body；请勿包含 code、pre 等代码元素，避免污染等宽字体。

内置字体清单

预设：思源黑体/宋体（简/繁）、霞鹜文楷（屏幕阅读版）、站酷小薇体、站酷快乐体、站酷庆科黄油体、马善政毛笔、刘健毛草体、志莽行书、龙藏体

推荐：得意黑、阿里妈妈东方大楷、钉钉进步体、霞鹜新晰黑、霞鹜漫黑、MiSans、悠哉字体、小赖字体、鸿雷行书、猫啃珠圆体、975 圆体、霞鹜文楷（原版）

所有字体均可免费商用，CSS 地址经过加速规则转换。

开发

环境要求：JDK 21、Node.js 18+、pnpm

# 安装前端依赖（首次）
cd ui && pnpm install

# 构建插件（自动先构建前端，再打包 jar，产物在 build/libs）
./gradlew build

# 本地调试（需要 Docker，自动启动 Halo 并加载插件）
./gradlew haloServer

技术栈：Java 21 + Spring WebFlux（CustomEndpoint / TemplateHeadProcessor）、Vue 3 + @halo-dev/ui-plugin-bundler-kit（Console 管理界面，IIFE 构建）。

许可证

GPL-3.0