PDF生成中文乱码或空白的根本原因是字体缺失：wkhtmltopdf需显式指定中文字体路径并用file://协议；Playwright/Puppeteer需在Docker中安装字体包并提前注入base64字体；pdfkit必须用registerFont加载本地字体文件且路径有效。
PDF 生成时中文乱码或空白，核心是字体缺失
HTML 转 PDF 工具（如 wkhtmltopdf、pdfkit、playwright 或浏览器 printToPDF）默认不嵌入中文字体，而系统级 PDF 渲染器（尤其 Linux/macOS）常无中文字体可用。结果就是：中文被跳过、显示为方块、或直接留空。
wkhtmltopdf 必须指定中文字体路径
它不读取系统字体配置，必须显式用 --font-family + --load-error-handling ignore 配合 @font-face 或 --user-style-sheet 注入字体。常见踩坑点：
-
wkhtmltopdf在 CentOS/Ubuntu 上默认没装fonts-wqy-zenhei或fonts-noto-cjk - 即使本地有
simhei.ttf，Linux 下路径需绝对且可读（/usr/share/fonts/truetype/wqy/wqy-zenhei.ttc） - CSS 中
@font-face的src: url(...)必须是本地文件路径（file:///协议），HTTP 地址无效
@font-face {
font-family: 'WenQuanYi';
src: url('file:///usr/share/fonts/truetype/wqy/wqy-zenhei.ttc');
}
body { font-family: 'WenQuanYi', sans-serif; }
Playwright / Puppeteer 中文渲染失败，别只改 CSS
它们基于 Chromium，看似支持中文，但 Docker 环境或精简系统缺字体库，CSS 指定字体也无效。关键动作是：
把任意文章或文档内容转换成精美的全屏翻页 HTML 演示文件（幻灯片风格）。当用户发来一篇文章、文档链接、Markdown 内容、或粘贴的文本，并且希望生成演示用的 HTML 时触发。支持任意内容来源：iWiki 链接、KM 链接、本地文件路径、直接粘贴的文本。生成的 HTML 文件保存到本地工作区，并通过企微直接发送给用户。触发词示例：帮我把这篇文章做成PPT、转成演示文档、生成HTML幻灯片、做个演示、转成可以演示的格式、article to deck、make a slide。
- 启动时传入
--font-render-hinting=none和--disable-font-subpixel-positioning（减少渲染干扰） - Docker 镜像必须安装中文字体包：
apt-get install -y fonts-wqy-zenhei fonts-noto-cjk - 在页面加载前注入字体声明（不能等 DOMContentLoaded）：
page.addStyleTag({ content: '@font-face{font-family:"Noto";src:url("data:font/ttf;base64,...")}' }) - 避免用
font-family: "Microsoft YaHei"—— 容器里根本不存在
pdfkit + Node.js 中文失效，不是编码问题而是字体链断裂
pdfkit 不解析 HTML/CSS，它只按指令画字。你写 doc.font('SimSun').text('你好')，前提是 SimSun.ttf 文件已用 doc.registerFont() 加载成功。否则静默回退到无中文的默认字体。
- 必须调用
doc.registerFont('SimSun', '/path/to/simsun.ttc')，路径必须存在且可读 - .ttc 文件（如
simsun.ttc）比 .ttf 更兼容，推荐优先用 - 不能依赖
fs.readFileSync同步读取网络路径或相对路径未 resolve 的路径 - 中文段落要手动换行（
text(..., { lineBreak: true })），PDFKit 不自动处理 HTML 白空间
const PDFDocument = require('pdfkit');
const doc = new PDFDocument();
doc.registerFont('NotoSansCJK', './NotoSansCJKsc-Regular.otf');
doc.font('NotoSansCJK').fontSize(12).text('测试中文正常显示');
字体加载和路径校验比编码设置重要得多；很多人花半天调 charset=utf-8，其实问题出在 file:///usr/share/fonts/... 根本打不开。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
