pdf 中文显示为方块或空白的主因是字体缺失：wkhtmltopdf 需显式指定中文字体路径并启用本地文件访问；itext7/pdfhtml 必须通过 fontprovider 手动注册字体；puppeteer/playwright 则需在容器中预装字体或内联 base64 字体。
中文在 PDF 里显示为方块（□）或空白，不是 HTML 写错了，而是 PDF 渲染器压根没找到能画中文的字体——它不查系统字体库，也不 fallback，缺啥就漏啥。
wkhtmltopdf 中文乱码：必须显式指定字体路径
它默认只认 DejaVu Sans，对 simsun、Microsoft YaHei、Noto Sans CJK SC 一概无视。即使 CSS 写了 font-family: "Microsoft YaHei"，只要系统没装这个字体，或者没告诉 wkhtmltopdf 去哪找，就会直接跳过中文。
- 用
--encoding utf-8强制编码（wkhtmltopdf 54+ 必须加，否则 meta charset 无效） - CSS 里必须用
@font-face，且src: url("file:///usr/share/fonts/truetype/wqy/wqy-zenhei.ttc")是绝对路径，file://协议不能省 - 启动时加
--enable-local-file-access，否则url()被拦截 - 别依赖
sans-serif或system-ui，PDF 引擎根本不认识这些别名
iText7 / pdfHTML 中文字体不生效：ConverterProperties 是关键
HtmlConverter.convertToPdf() 不会自动加载系统字体，也不会解析 CSS 里的 @font-face。它只认你手动注册进 ConverterProperties 的字体对象。
- 必须调用
converterProperties.setFontProvider(...)，传入一个带中文字体文件路径的FontProvider - 推荐用
FontProgramFactory.createFont("/path/to/NotoSansCJKsc-Regular.ttf")加载，别用 classpath 资源路径（容易找不到） - HTML 里仍要写
font-family: "Noto Sans CJK SC"，名字必须和注册时一致（区分大小写） -
<meta charset="UTF-8">必须有，但仅防 HTML 解析错误；字体缺失才是乱码主因
Puppeteer / Playwright 导出 PDF：字体得提前塞进容器
Chromium 在无 GUI 的 Linux 环境里，连 fc-list 都看不到中文字体。它不读 /etc/fonts/conf.d/，只从系统 fontconfig 缓存里查——而 Docker 默认不建缓存。
- Dockerfile 里加：
RUN apt-get install -y fonts-wqy-zenhei && fc-cache -fv - 或者更稳：把 .ttf 文件 base64 内联进 CSS 的
@font-face，src 用data:font/truetype;base64,... - 启动浏览器时加
args: ["--font-render-hinting=none"]可缓解部分渲染抖动 - 别信“本地能跑线上就能跑”——服务器没装字体，就是白屏
真正卡住交付的，从来不是“能不能转出来”，而是“转出来的 PDF 能不能盖章、能不能被法院采信”。字体嵌入是否完整、文本能否复制、超链接是否存活、分页是否可控——这些细节在生成命令里多加一个参数，或在 CSS 里多写一行 @font-face，就决定了是能用，还是只能删掉重来。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
