html2pdf转换时字体样式丢失如何解决？

Question

在使用 html2pdf 进行 HTML 转 PDF 时，常遇到字体样式丢失的问题，如自定义字体（Google Fonts）、特殊字号或加粗斜体等样式未能正确渲染。主要原因在于 html2pdf 默认不支持远程字体加载，也无法识别部分 CSS 样式。 解决方法包括： 1. **将字体转换为 Base64 并内联嵌入 CSS**，确保 pdf 生成工具可识别； 2. 使用 `@font-face` 定义字体路径，并确保其为本地路径或允许跨域加载； 3. 在 html2pdf 配置中启用 `useCORS: true`，并合理设置 `allowTaint` 参数，以支持外部资源加载； 4. 对关键文本应用系统内置字体，避免依赖远程字体文件。 通过上述优化手段，可显著提升 html2pdf 中字体样式的保真度与一致性。

Answer 1

一、问题背景与常见现象

在使用 html2pdf 将 HTML 内容转换为 PDF 的过程中，开发者常常遇到字体样式丢失的问题。例如：

• 自定义字体（如 Google Fonts）未正确加载；
• 加粗（font-weight: bold）、斜体（font-style: italic）等样式未能渲染；
• 特殊字号（如 14px、18px）在 PDF 中显示异常。

这些问题的核心原因在于 html2pdf 依赖于浏览器的 DOM 渲染机制，而默认情况下无法加载远程资源（如外部字体文件），也无法完全识别所有 CSS 样式。

二、深入分析：html2pdf 的字体处理机制

html2pdf 实质上是基于 html2canvas 和 jsPDF 的封装库。其工作流程如下：

1. 将 HTML 内容渲染为 canvas 图像；
2. 将图像分页并导出为 PDF。

由于字体渲染发生在浏览器端，因此存在以下限制：

问题类型	说明
跨域字体文件	浏览器出于安全策略，默认阻止跨域请求字体资源。
异步加载字体	html2pdf 在生成 PDF 时可能未等待字体加载完成。
CSS 兼容性问题	部分 CSS 属性或伪类样式无法被 html2canvas 正确解析。

三、解决方案详解

1. 将字体转换为 Base64 并内联嵌入 CSS

为了确保字体资源不依赖外部加载，可以将字体文件（如 .woff 或 .ttf）转换为 Base64 编码，并直接嵌入到 CSS 中。示例代码如下：

@font-face {
    font-family: 'CustomFont';
    src: url(data:font/woff;charset=utf-8;base64,d09GRgABAA...省略Base64编码) format('woff');
}

2. 使用 @font-face 定义本地字体路径

如果字体文件部署在本地服务器上，需确保路径正确且允许跨域访问。配置示例如下：

@font-face {
    font-family: 'Roboto';
    src: url('/fonts/roboto.ttf') format('truetype');
}

3. 配置 html2pdf 支持 CORS 和外部资源

在初始化 html2pdf 时，开启跨域支持和图像污染选项：

html2pdf().set({
    useCORS: true,
    allowTaint: false
}).from(element).save();

4. 对关键文本应用系统内置字体

对于对视觉呈现要求较高的内容，建议使用操作系统自带的通用字体，如：

• Windows：Arial, Times New Roman
• macOS：Helvetica, Lucida Grande

四、优化建议与最佳实践

结合上述方法，以下是推荐的优化流程图：

graph TD
            A[开始] --> B{是否使用远程字体?}
            B -- 是 --> C[转换字体为Base64]
            B -- 否 --> D[使用本地@font-face]
            C --> E[内联CSS至HTML]
            D --> E
            E --> F[设置useCORS: true]
            F --> G[测试渲染效果]
            G --> H[输出PDF]

此外，还可以通过监听字体加载状态来延迟 PDF 生成时机：

document.fonts.ready.then(() => {
    html2pdf().from(element).save();
});