HTML转PDF乱码主因是字体缺失或编码未识别，须显式指定中文字体、声明UTF-8、禁用系统默认字体；pdfkit需@font-face加载本地字体并启用local-file-access；wkhtmltopdf需绝对路径+该参数；weasyprint需系统注册字体名；WebFont须本地化且避免swap和unicode-range。
HTML 转 PDF 出现乱码，绝大多数情况不是转换工具本身的问题，而是字体缺失或编码声明未被正确识别导致的。核心对策是：显式指定中文字体 + 确保 HTML 声明 UTF-8 + 避免依赖系统默认字体。
用 pdfkit 时中文不显示或显示为方块
pdfkit（基于 wkhtmltopdf）默认不支持中文字体，即使 HTML 中写了 <meta charset="UTF-8"> 也无效。它需要在生成时通过 CSS 显式指定一个已安装的中文字体文件路径。
- 确保系统已安装支持中文的 TrueType 字体（如
NotoSansCJKsc-Regular.ttf、simhei.ttf或msyh.ttc） - 在 HTML 的
<style>中强制设置body和常用标签的font-family，且必须包含完整字体路径（Windows 下注意双反斜杠或原始字符串） - 调用
pdfkit.from_file()或.from_string()时传入options={'enable-local-file-access': ''}，否则本地字体文件无法加载
body {
font-family: "Noto Sans CJK SC", "SimHei", "Microsoft YaHei", sans-serif;
}
@font-face {
font-family: "Noto Sans CJK SC";
src: url("./fonts/NotoSansCJKsc-Regular.ttf") format("truetype");
}
wkhtmltopdf 命令行直接转 PDF 仍乱码
命令行方式更易忽略字体上下文。wkhtmltopdf 不读取系统字体配置，只认 CSS 中 @font-face 加载的本地路径，且该路径必须可被 wkhtmltopdf 进程访问（不能是浏览器相对路径）。
- 把字体文件放在与 HTML 同目录或绝对路径下，并在 CSS 中用绝对路径引用（如
file:///home/user/fonts/simhei.ttf） - 加参数
--enable-local-file-access，否则file://协议会被拒绝 - 避免使用
--encoding utf-8参数——wkhtmltopdf 54+ 版本已弃用该参数，实际以 HTML 中的<meta charset="UTF-8">为准
用 weasyprint 渲染中文 PDF 仍缺字
weasyprint 对字体处理比 pdfkit 更透明，但它不会自动 fallback 到系统中文字体，必须在 CSS 中明确指定可用字体族名（不是文件名），且该字体名需已在系统字体库中注册。
立即学习“前端免费学习笔记（深入）”；
- Linux 下运行
fc-list :lang=zh查看已注册的中文字体名（如WenQuanYi Micro Hei） - CSS 中写
font-family: "WenQuanYi Micro Hei", sans-serif;，不要写.ttf文件路径 - macOS 上常见字体名是
"PingFang SC"，Windows 是"Microsoft YaHei"；跨平台部署建议打包字体并用@font-face加载
HTML 中用了 WebFont（如 iconfont）但 PDF 里图标变空白
WebFont 多数依赖网络请求或 base64 内联，而 pdf 生成工具默认禁用网络请求，base64 字体也可能因解析限制失效。
- 把 iconfont 的
.woff2或.ttf文件下载到本地，改用@font-face指向本地路径 - 确认字体文件的
font-display不设为swap（PDF 渲染无异步机制） - 避免使用
unicode-range子集切割——部分工具不支持，会导致字符映射失败
真正容易被忽略的是：字体文件权限（Linux/macOS 下需可读）、CSS 中字体名与系统注册名不一致、以及 @font-face 的 src 路径在不同工具中行为差异极大——pdfkit 认路径，weasyprint 认字体名，headless Chrome（Puppeteer）则两者都支持但需额外配置。别指望“写个 meta 就能好”。
