HTML嵌入字体转PDF技巧分享

HTML转PDF时字体丢失、显示为方块或默认宋体，根本原因并非“未嵌入”，而是@font-face加载失败、PDF工具（如weasyprint、wkhtmltopdf）不支持远程/网络字体、仅识别本地.ttf/.otf文件，且对路径、格式、字体家族名匹配极为敏感；weasyprint依赖同目录下正确声明的本地.ttf文件，而wkhtmltopdf则需将字体安装至系统并确保CSS中使用的font-family名称与系统注册名完全一致，同时忽略font-display和JavaScript；此外，中文字体体积庞大，务必通过pyftsubset提取字符子集以避免PDF臃肿和乱码——真正卡点往往藏在静默失败的路径错误、格式不兼容或名称不匹配中。

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 写的不一致 —— 这些错误通常没有明确报错，只静默回退到默认字体。

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《HTML嵌入字体转PDF技巧分享》文章吧，也可关注golang学习网公众号了解相关技术文章。