17370845950

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 指定字体也无效。关键动作是：

• 启动时传入 --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/... 根本打不开。