HTML转PDF字体丢失的根本原因是@font-face加载失败、PDF工具不支持远程字体且仅认本地.ttf/.otf文件；weasyprint需同目录.ttf+正确声明，wkhtmltopdf须系统安装字体并匹配家族名。
HTML 转 PDF 时字体丢失、显示为方块或默认宋体，根本原因不是“没嵌入”，而是 @font-face 加载失败 + PDF 工具不支持远程字体 + 字体格式/路径未正确声明。
PDF 工具对字体的实际处理逻辑
像 wkhtmltopdf、weasyprint、pdfkit（基于 wkhtmltopdf）这类工具，**不会执行 JavaScript，也不加载跨域 CSS 中的 url() 字体**。它们只解析 HTML 和内联/同域 CSS，并且仅支持本地字体文件（file:// 或绝对路径），且要求字体格式为 .ttf 或 .otf（.woff/.woff2 基本无效）。
-
wkhtmltopdf从系统字体目录读取字体（如 Linux 的/usr/share/fonts），或通过--font-path指定目录 -
weasyprint支持@font-face，但要求src: url(...)指向本地可读的.ttf文件（相对路径需相对于 HTML 文件位置） - 所有工具均忽略
CSS font-display: swap，不等待字体加载完成就渲染
weasyprint：用 @font-face + 本地 .ttf 最可靠
这是目前对自定义字体支持最透明的方案。关键点：字体文件必须与 HTML 同目录（或使用准确相对路径），且声明中不能含协议头或域名。
@font-face {
font-family: 'HarmonyOS Sans';
src: url('HarmonyOS_Sans_SC_Regular.ttf') format('truetype');
font-weight: normal;
font-style: normal;
}
对应 HTML 中：
立即学习“前端免费学习笔记（深入）”；
- 确保
HarmonyOS_Sans_SC_Regular.ttf和 HTML 文件在同一目录下 - 不要写成
url('./fonts/HarmonyOS_Sans_SC_Regular.ttf')，除非你确认路径层级完全匹配 - 避免使用中文文件名（部分版本
weasyprint解析失败） - 用
weasyprint --verbose input.html output.pdf查看是否报WARNING: Failed to load font
wkhtmltopdf：绕过 CSS，直接注册系统字体
它几乎不认 @font-face，推荐把字体安装到系统，再用 CSS 指定家族名（不是文件名）。
- Linux：复制
.ttf到/usr/share/fonts/truetype/custom/，运行sudo fc-cache -fv -
macOS：双击安装到“字体册”，或复制到
~/Library/Fonts/ - Windows：右键字体 → “为所有用户安装”
- 然后在 HTML 中直接写：
body { font-family: "HarmonyOS Sans", sans-serif; } - 启动时加参数强制识别：
wkhtmltopdf --font-path /usr/share/fonts/truetype/custom/ input.html output.pdf
注意：CSS 中写的 font-family 名称必须和系统注册的全名一致，可用 fc-list | grep -i harmony（Linux/macOS）验证。
字体子集与体积控制（容易被忽略的坑）
一个完整中文字体常超 10MB，PDF 嵌入后体积暴增，且 weasyprint 默认会嵌入全部字形 —— 即使你只用了“你好世界”四个字。
- 用
pyftsubset（来自fonttools）提取所需字符：pyftsubset HarmonyOS_Sans_SC_Regular.ttf --text="你好世界123" --output-file=subset.ttf - 再把这个
subset.ttf用于@font-face或系统安装 -
wkhtmltopdf不支持子集，但系统级安装小字体能加快渲染 - 如果生成 PDF 后文字仍乱码，检查字体是否含 Unicode BMP 外字符（如 emoji、生僻汉字），这些很可能被丢弃
真正卡住的地方往往不是“怎么嵌”，而是字体文件路径没对上、格式不被认、或者系统里注册的名字和 CSS 写的不一致 —— 这些错误通常没有明确报错，只静默回退到默认字体。
