Symfony生成PDF方法：DomPDF与Snappy教程

在 Symfony 中生成 PDF 绝非简单安装扩展即可，DomPDF 与 Snappy 的常见失败——中文乱码、空白页面、页眉失效或静默崩溃——根源往往不在代码逻辑，而在于字体注册缺失、资源路径未绝对化、子进程权限不足及 HTML 上下文隔离失控这四大隐性陷阱；本文直击实战痛点，手把手教你为 DomPDF 正确加载中文字体、为 Snappy 稳定调用 wkhtmltopdf、规避模板渲染雷区，并提供带内容校验的安全导出方案，助你在本地开发、Docker 容器乃至 CI/CD 流水线中稳定生成可信赖的 PDF。

DomPDF 和 Snappy 都能用，但选错一个会卡在中文乱码、页眉页脚不生效、或 PDF 渲染空白上——关键不在“怎么装”，而在“怎么配字体和上下文”。

DomPDF 中文乱码的根本原因和解法

DomPDF 默认不加载中文字体，mb_convert_encoding 或 iconv 强转编码只是掩耳盗铃，真正要的是注册字体+指定字体族。

• 把 simhei.ttf（或 NotoSansCJKsc-Regular.otf）放到 public/fonts/ 目录下
• 在 config/packages/dompdf.yaml 里显式声明字体路径：

  dompdf:
    options:
      font_dir: '%kernel.project_dir%/public/fonts'
      font_cache: '%kernel.project_dir%/var/cache/dompdf/fonts'

• 在 Twig 模板中用 @font-face 注册并强制使用：

  @font-face {
    font-family: 'SimHei';
    src: url('{{ absolute_url('fonts/simhei.ttf') }}') format('truetype');
  }
  body { font-family: 'SimHei', sans-serif; }

• 避免在模板里用 {{ entity.title|raw }} 直接输出未转义 HTML，DomPDF 对非法标签极敏感，容易静默失败

Snappy（wkhtmltopdf）生成空白 PDF 的常见触发点

Snappy 本身不渲染，它调用 wkhtmltopdf 命令行工具，空白 PDF 多数是子进程执行失败但没抛异常。

• 确认 wkhtmltopdf 已安装且可执行：which wkhtmltopdf 或 wkhtmltopdf --version
• 在 Symfony 中配置时必须指定完整路径（尤其 Docker 或生产环境）：

  knplabs_knp_snappy:
    pdf:
      binary: '/usr/local/bin/wkhtmltopdf'
      timeout: 60

• 禁用远程资源加载（如 CDN 字体、外部 CSS）：默认 enable-javascript 和 no-stop-slow-scripts 可能导致超时，建议显式关闭：

  $snappy->setOption('enable-javascript', false);
  $snappy->setOption('no-stop-slow-scripts', true);

• Twig 模板里不要用 localhost 或 127.0.0.1 加载 CSS/JS，Snappy 在无网络容器里无法解析；改用绝对 URL 或内联样式

在 Controller 中安全导出 PDF 的最小可行写法

别直接返回 Response，先生成再校验内容长度，否则空 PDF 也会返回 200。

• 用 generateFromHtml() 而非 generate()，避免文件路径权限问题：

  $html = $this->renderView('pdf/invoice.html.twig', ['invoice' => $invoice]);
  $pdfContent = $this->get('knp_snappy.pdf')->generate($html); // 或 $this->get('dompdf.wrapper')->stream('invoice.pdf');

• 加一层空内容检查：

  if (empty($pdfContent) || strlen($pdfContent) 

• 设置正确 header：

  return new Response(
      $pdfContent,
      200,
      [
          'Content-Type' => 'application/pdf',
          'Content-Disposition' => 'attachment; filename="invoice.pdf"',
      ]
  );

字体注册、路径绝对化、子进程权限、HTML 上下文隔离——这四点漏掉任一个，PDF 就可能成功“生成”却打不开。尤其在 CI/CD 或容器部署时，wkhtmltopdf 的二进制兼容性和 DomPDF 的缓存目录写权限，比语法错误更难排查。

今天关于《Symfony生成PDF方法：DomPDF与Snappy教程》的内容介绍就到此结束，如果有什么疑问或者建议，可以在golang学习网公众号下多多回复交流；文中若有不正之处，也希望回复留言以告知！