如何让wkhtml2pdf使用本地系统字体适配pre标签代码块样式

本地字体调用解决方案 #

wkhtml2pdf基于旧版Qt WebKit引擎渲染，本身支持调用本地字体，按以下步骤配置即可生效：

• 先确认你要使用的字体在运行环境的正式名称完全匹配：Windows可在控制面板-字体页面查看字体的完整名称，macOS可在字体册中选中字体按⌘+I查看「系列名称」，Linux可执行fc-list命令列出所有已安装字体的正式名称，注意大小写、空格必须完全一致。
• 优先使用@font-face显式声明本地字体，比直接调用系统字体稳定性更高，示例配置如下：

@font-face {
  font-family: "Consolas Local";
  /* 先匹配系统安装的字体，匹配失败则读取本地字体文件 */
  src: local("Consolas"),
       /* 以下按你的运行环境选填对应的字体文件路径 */
       url("file:///C:/Windows/Fonts/consola.ttf") format("truetype"); /* Windows路径示例 */
       /* url("file:///Library/Fonts/Consolas.ttf") format("truetype"); */ /* macOS路径示例 */
       /* url("file:///usr/share/fonts/consola.ttf") format("truetype"); */ /* Linux路径示例 */
  font-weight: normal;
  font-style: normal;
}

pre, pre > code {
  font-family: "Consolas Local", monospace !important;
}

• 执行wkhtml2pdf命令时必须添加--enable-local-file-access参数，允许渲染器读取本地文件资源。
• 如果是Linux无桌面环境，字体安装到系统目录后需要执行fc-cache -fv刷新字体缓存，再执行转换操作。

monospace通用字体标识不生效的原因 #

这是旧版Qt WebKit引擎的固有特性，和现代Chromium内核的字体 fallback 逻辑不同：

• 现代浏览器默认会将monospace通用字体族映射到系统预设的等宽字体，而wkhtml2pdf使用的内核没有内置该映射规则，monospace会直接指向全局配置的默认非等宽字体。
• 部分精简的Linux服务器环境默认没有预装任何等宽字体，就算有映射规则也找不到匹配字体，最终还是会回落到全局默认字体。

内容的提问来源于stack exchange，提问作者Rick Strahl