wkhtmltopdf/PDFKit转HTML为PDF时字体与单元格背景色渲染异常

云上老周

2026-8-29

问题原因

PDFKit底层封装的渲染内核是wkhtmltopdf，基于老旧的Qt WebKit实现，和日常预览HTML用的Chrome/Edge等现代浏览器的Blink内核在默认样式、渲染逻辑上存在本质差异，二者渲染结果天然无法做到开箱100%对齐。
Bootstrap 5的原生系统字体栈定义在body选择器上，依赖现代浏览器自带的系统字体匹配规则生效，但wkhtmltopdf内置的用户代理样式表没有做Windows平台的字体映射，没有更高优先级显式字体声明时，它会直接跳过Bootstrap的字体规则，调用自身内置的默认衬线字体，不会加载系统里已安装的Segoe UI。
单元格背景色异常是wkhtmltopdf存在多年的已知bug：当页面没有全局显式的font-family声明时，内核会自动触发打印场景的默认样式覆盖逻辑，强制把表格单元格等元素的背景色设为透明，适配传统无背景打印的需求。这也是为什么加了全局字体规则后，字体和背景色的问题会同时消失，和Bootstrap本身的样式写法没有关联。

修复方案

最小改动方案：直接保留你测试通过的全局显式字体声明即可，注意建议把字体规则挂在通配选择器上，覆盖所有元素，避免表格、表单这类特殊元素被内核默认样式覆盖：

* {
    font-family: 'Segoe UI', Arial, sans-serif;
}

如果发现局部元素还是有样式异常，可以给这条规则加!important提升优先级。

渲染参数调优方案：不需要修改CSS，在调用PDFKit生成PDF时传入指定参数，关闭内核的默认打印样式覆盖，强制渲染背景元素，同时放开本地文件访问权限，避免本地CSS加载不全：

import pdfkit

render_options = {
    "page-size": "A4",
    "margin-top": "10mm",
    "margin-bottom": "10mm",
    "margin-left": "10mm",
    "margin-right": "10mm",
    "enable-local-file-access": None,
    "background": None,
    "disable-smart-shrinking": None,
    "encoding": "UTF-8"
}
pdfkit.from_file("your_report.html", "output.pdf", options=render_options)

另外引用本地Bootstrap资源时建议使用相对路径，不要用file:///开头的绝对路径，避免触发内核的本地文件安全拦截导致部分规则加载失败。

最稳定方案：将用到的Segoe UI字体文件放到项目静态资源目录，通过@font-face规则做本地字体引入，完全不依赖系统安装的字体，彻底规避不同环境下的字体加载差异，同时也不会触发wkhtmltopdf的怪异渲染逻辑。

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