Dompdf 中文显示解决方案：UTF-8编码与中文字体设置指南

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

许多开发者在利用 Dompdf（v0.8.0及以上版本）生成包含中文的 PDF 文档时，常会遇到一个典型问题：HTML 页面预览时中文显示正常，但导出为 PDF 后，所有汉字都变成了“□”方块符号。这通常并非代码错误，而是因为 Dompdf 本身缺乏内置的中文字体支持。其默认的 DejaVu Sans 字体虽涵盖部分 Unicode 字符，但并未包含汉字字形。

因此，要确保中文正常显示，必须主动为 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 中文显示常见陷阱与排查

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

• 路径错误：DOMPDF_FONT_DIR 使用了相对路径，导致字体无法加载。
  解决方案：使用 __DIR__ 或 realpath() 构建绝对路径。
• 名称不匹配：defaultFont 设置的值与字体文件名不符。例如设置为 ‘NotoSansCJKtc’，但实际文件名为 ‘NotoSansCJKtc-Regular.ttf’。
  解决方案：确保名称严格一致，最稳妥的方式是直接使用字体文件名的前缀。
• 配置遗漏：仅定义了常量 DOMPDF_FONT_DIR，却未调用 $options->set('fontDir', ...)。在 v0.8+ 版本中，常量不会自动生效。
  解决方案：必须显式设置 fontDir 选项。
• 远程加载冲突：服务器禁用了 allow_url_fopen，但同时开启了 isRemoteEnabled 选项，可能导致意外失败。
  解决方案：对于字体等核心资源，建议本地托管，并考虑关闭远程加载选项。

如何验证 Dompdf 中文配置成功

验证配置是否生效有一个直观的方法：首次成功运行脚本后，Dompdf 会在指定的字体目录中自动解析 TTF 文件，并生成对应的 .ufm 和 .php 缓存文件。检查 assets/fonts/ 目录，若出现类似 notosanscjktc-regular.ufm 的文件，则表明字体已成功注册。

若缓存文件已生成但 PDF 中仍显示方块，请检查 PHP 错误日志，问题可能源于文件读取权限或最终路径错误。

按照以上步骤正确配置后，Dompdf 即可稳定生成文字清晰、支持选中的中文 PDF 文档，无论是报表、合同还是其他多语言文档，都能轻松应对。