模板字体设置

由于此前的模板字体配置方案较为粗糙，仅将用户配置的 templateFonts font-family 字符串写入到模板中的 css font-family，这要求 koishi 运行环境（也就是系统）中必须已安装相应字体文件。在一些环境中（如 docker 镜像、精简版 linux 等）还需自行补齐字体管理工具，部署难度较高。

因此，插件在2.4.0版本实现了新的字体管理方案，允许上传字体文件并可配置三种字体样式 (sans, serif, mono) 对应的字体列表，根据列表排序决定回退顺序（即优先级）。

现在插件在调用 puppeteer 生成图片时注入字体文件的静态路径与 css font-face 注册代码，从而无须依赖系统环境字体。

安装字体文件

默认情况下的 字体目录 为 data/fonts/dota2tracker，可于配置项 fontPath 修改。

可切换到 资源管理器 找到 字体目录 文件夹并右键点击，在弹出的菜单中选择 上传文件 拖入字体文件进行上传。

资源管理器
├ data/
│ ├ assets/
│ ├ ...
│ └ fonts/
│   └ dota2tracker/  <-- 在这里放入字体文件
│     ├ fontA.ttf
│     ├ fontB.otf
│     ├ fontC.ttc
│     └ ...

字体的加载

插件会自动读取 字体目录 下的所有字体文件，并使用 fontkit 依赖包读取字体元数据。

字体文件格式支持 .ttf, .otf, .woff, .woff2, ttc, sfnt。

读取后会生成字体名列表，将自动对应到 fonts.* 配置项的下拉框，可以便利地添加项并选择已加载的字体。

插件会将不同字重/样式的同一字体合并，以适配不同场景，但不同语言版本不会合并。

例如：

[加载前] 字体目录文件列表：
├─ SourceHanSans-Bold.otf      (思源黑体-国际版-粗体)
├─ SourceHanSans-Regular.otf   (思源黑体-国际版-常规)
├─ SourceHanSans-SC-Bold.otf   (思源黑体-简中版-粗体)
└─ SourceHanSans-SC-Regular.otf(思源黑体-简中版-常规)

[加载后] 配置项下拉框可选列表：
├─ Source Han Sans      (自动合并 国际版-粗体 与 国际版-常规)
└─ Source Han Sans SC   (自动合并 简中版-粗体 与 简中版-常规)

字体推荐

本段声明

仅代表个人喜好。

fonts.sans

正文字体 / Body Text

【推荐】首选方案：国内厂商字体

推荐直接使用国内手机厂商推出的字体，如 OPPO Sans、MiSans。 这类字体主要面向国内用户，以简中字形为主的同时覆盖了尽可能多的外文文字，最大限度地保证了显示效果与不缺字。 通常只需下载并配置这一个字体族即可满足绝大多数需求，省心省力。

【进阶】手动组合：多字体回退

得益于新的多字体回退机制，现在可以同时利用多个针对不同语言优化的字体。

例如，可以组合使用 Roboto (优秀的英文字体) 与 Noto Sans SC (优秀的简体中文字体)。 将 Roboto 放置在列表首位，Noto Sans SC 紧随其后。这样在渲染英文数字时会优先使用 Roboto，而在渲染汉字时则会自动回退使用 Noto Sans SC。 这种组合方式既保留了英文字体的美感，也确保了中文字符的正确显示。

关于“国际化”字体（如思源黑体）的注意事项

像 思源黑体(SourceHanSans) 这类国际化字体，它们为简中、繁中、日文、韩文等不同语言与地区的异体字形差异提供了严格的版本区分。

如果单一使用 CN/SC(简中版) 字体文件，在遇到日文假名时可能会因缺字而触发回退，导致显示为 ▢ 或回退到系统默认字体，影响视觉效果。

此时利用多字体回退机制，可以在中文版字体后配置其他语言版本（如日文版）作为补充后备，即可兼顾多种语言的显示需求。

fonts.serif

标题字体 / Title Text

衬线字体推荐使用楷体这类有些书法气息的字体，推荐霞鹜文楷(LxgwWenKai)。

fonts.mono

代码、数字字体 / Code & Number Text

等宽字体的选择非常多，霞鹜文楷同样提供了 mono 字体 LXGWWenKaiMono-*.ttf，也可以搜索一些如JetBrains Mono这样的“代码优化”字体。

也可以此处留空，会自动回退至 fonts.sans 配置，保持和正文字体风格一致。