Dompdf 中文显示问题解决方案 UTF8 编码与字体设置指南

Dompdf 默认不支持中文，需显式配置中文字体路径、启用 Unicode、设置兼容字体（如 Noto Sans CJK），并确保 HTML 编码与字体文件加载一致，否则中文会显示为方块。

许多开发者在利用 Dompdf（v0.8.0 及以上版本）生成包含中文内容的 PDF 文档时，都会遇到一个典型问题：HTML 页面在浏览器中预览一切正常，但一旦导出为 PDF，所有中文字符就统一变成了“□”方块。这并非代码错误，而是 Dompdf 本身的一个设计特点——它缺乏内置的中文字体支持。其默认的 DejaVu Sans 字体虽然涵盖了大量 Unicode 字符，但并未包含汉字字形。

因此，要让中文内容在 PDF 中正确渲染，您必须主动引导 Dompdf，告知它应使用何种字体以及从何处加载。以下这套四步解决方案，将帮助您彻底解决 Dompdf 中文显示乱码的问题。

✅ 正确解决方案（四步到位）

1. 准备支持中文的 TrueType 字体文件

字体是基础。推荐使用 Google 开源的 Noto Sans CJK 系列字体，它全面覆盖简体中文、繁体中文、日文和韩文，字形清晰且允许免费商用。常用文件例如：

• NotoSansCJKtc-Regular.ttf（繁体中文常规体）
• NotoSansCJKsc-Regular.ttf（简体中文常规体）

下载字体文件后，将其统一放置于项目的特定目录中，例如 assets/fonts/。此处有一个关键细节：必须确保 PHP 进程拥有读取该目录的权限，否则后续所有配置都将无效。

2. 显式配置字体目录与默认字体

接下来，在初始化 Dompdf 时，必须明确指定字体存放路径和默认使用的字体。参考以下代码：

require 'vendor/autoload.php'; // 请根据您的项目结构调整自动加载路径

// ⚠️ 关键步骤：定义字体存储目录，此处必须使用绝对路径
define('DOMPDF_FONT_DIR', __DIR__ . '/assets/fonts/');

$options = new Options();
$options->set('fontDir', DOMPDF_FONT_DIR);     // 告知 Dompdf 在此路径查找字体
$options->set('defaultFont', 'NotoSansCJKtc-Regular'); // 设置默认中文字体（注意：省略 .ttf 后缀）
$options->set('isPhpEnabled', false);           // 生产环境建议关闭以提升安全性
$options->set('isRemoteEnabled', true);        // 如需加载网络图片等资源可开启，但需注意风险
$dompdf = new Dompdf($options);

? 重要提示：defaultFont 参数的值，应填写字体的 PostScript 名称或文件名前缀，而非 CSS 中使用的 font-family 名称。如果不确定，直接使用字体文件的主文件名（去除 .ttf 扩展名）通常是安全的，例如 “NotoSansCJKtc-Regular”。

3. HTML 内容编码与结构规范

HTML 内容端也需要做好相应配合：

• 确保 HTML 头部明确声明了 UTF-8 编码：。
• 无需在 CSS 中使用 @font-face 规则加载字体（Dompdf v0.8+ 不解析此规则）。
• 不过，在 CSS 中保留 font-family 声明作为回退方案是可以的，尽管最终生效的是上一步设置的 defaultFont：

  body {
    font-family: 'NotoSansCJKtc-Regular', sans-serif;
    font-size: 14px;
  }

4. 安全编码处理（防止乱码）

最后一步，在加载 HTML 内容时，建议进行一次编码转换，这可以规避旧版本 Dompdf 在处理 UTF-8 字符串时可能存在的兼容性问题：

$html = $this->load->view('view_view', $data, TRUE);

// 将内容统一转换为 UTF-8 实体，以获得更好的兼容性
$html = mb_convert_encoding($html, 'HTML-ENTITIES', 'UTF-8');

$dompdf->loadHtml($html);
$dompdf->setPaper('A4', 'landscape');
$dompdf->render();
$dompdf->stream("Report.pdf", ['Attachment' => false]);

⚠️ 常见陷阱与排查清单

在配置过程中，以下几个问题尤为常见：

• ❌ 路径错误：DOMPDF_FONT_DIR 使用了相对路径，导致字体文件无法被正确加载。
  ✅ 修复方法：坚持使用 __DIR__ 或 realpath() 函数来构建绝对路径。
• ❌ 名称不匹配：defaultFont 设置的值与实际的字体文件名前缀不符。例如，填写了 ‘NotoSansCJKtc’，但字体文件名为 ‘NotoSansCJKtc-Regular.ttf’。
  ✅ 修复方法：确保名称严格一致，最稳妥的方式是直接使用字体文件的主文件名（不含扩展名）。
• ❌ 配置遗漏：仅定义了常量 DOMPDF_FONT_DIR，却忘记通过 $options->set('fontDir', ...) 进行设置。在 v0.8+ 版本中，常量不会自动生效。
  ✅ 修复方法：必须显式设置 fontDir 选项。
• ❌ 远程加载冲突：服务器禁用了 allow_url_fopen 配置，但您又开启了 isRemoteEnabled 选项，可能导致资源加载失败。
  ✅ 修复方法：对于字体这类核心资源，尽量采用本地托管方式，并考虑关闭远程加载选项以确保稳定。

✅ 验证配置是否成功

如何确认配置已生效？有一个非常直观的验证方法：首次成功运行脚本后，Dompdf 会自动在您指定的字体目录中，将 TTF 字体文件解析并生成对应的 .ufm 和 .php 缓存文件。请检查 assets/fonts/ 目录，如果出现了类似 notosanscjktc-regular.ufm 这样的文件，那么恭喜您，中文字体已成功注册。

如果缓存文件已生成但 PDF 中仍显示方块，请不要慌张。建议检查 PHP 错误日志，问题很可能出在文件读取权限或最终的路径解析上。

按照以上步骤完成配置后，Dompdf 便能稳定输出文字清晰、支持选中与搜索的中文 PDF 文档。无论是生成数据报表、电子合同还是其他多语言文档，都能轻松胜任。