本文共计970个文字，预计阅读时间需要4分钟。

如果您的PHP项目中需要将HTML内容转换为PDF文件，但生成结果存在样式错乱、中文缺失或执行失败等问题，可能是由于以下原因：

一、使用Composer管理wkhtmltopdf二进制（推荐）

该方法彻底规避系统级安装差异，确保开发、测试、生产环境二进制版本完全一致，避免因Ubuntu旧源包或Windows路径问题导致的渲染异常。

1、在项目根目录执行命令安装预编译二进制包：
composer require h4cc/wkhtmltopdf-amd64

2、确认二进制文件已部署至vendor/bin/wkhtmltopdf，且PHP进程具备执行权限

立即学习“PHP免费学习笔记（深入）”；

3、通过KnpSnappyBundle或直接调用Shell生成PDF：
$snappy = new Pdf('vendor/bin/wkhtmltopdf');
$snappy->generateFromHtml($htmlContent, '/tmp/report.pdf');

4、关键参数强制启用UTF-8与无背景渲染：--encoding utf-8 --no-background --enable-local-file-access

二、phpwkhtmltopdf库封装调用

该方案提供面向对象接口，自动处理错误捕获与选项合并，适合需多页、封面、目录等企业级PDF结构的场景。

1、执行命令安装PHP封装库：
composer require mikehaertl/phpwkhtmltopdf

2、引入自动加载并实例化Pdf类：
require 'vendor/autoload.php';
$pdf = new \mikehaertl\wkhtmlto\Pdf();

3、设置全局选项以适配中文显示：
$pdf->setOptions([
  'encoding' => 'UTF-8',
  'page-size' => 'A4',
  'margin-top' => 15,
  'margin-right' => 15,
  'margin-bottom' => 15,
  'margin-left' => 15
]);

4、添加含中文CSS的HTML页面：
$pdf->addPage('

订单详情

客户：张三

');

5、保存时检查返回值：
if (!$pdf->saveAs('/var/www/pdf/invoice_20260418.pdf')) {
  throw new Exception('PDF生成失败：' . $pdf->getError());
}

三、原生exec调用并增强容错

适用于轻量级需求或已有成熟Shell脚本集成的系统，通过显式路径、超时控制与错误重定向保障稳定性。

1、定义绝对路径避免PATH环境变量依赖：
$wkPath = '/usr/local/bin/wkhtmltopdf'; // 或 vendor/bin/wkhtmltopdf

2、构造带安全参数的命令行：
$cmd = escapeshellarg($wkPath) . ' --quiet --encoding utf-8 --no-outline --enable-local-file-access --page-size A4 ' . escapeshellarg($htmlFile) . ' ' . escapeshellarg($pdfFile);

3、设置30秒执行超时并捕获完整错误输出：
$descriptors = [1 => ['pipe', 'w'], 2 => ['pipe', 'w']];
$process = proc_open($cmd, $descriptors, $pipes, null, null, ['timeout' => 30]);

4、读取stderr判断是否发生字体缺失或JS超时：
$errorOutput = stream_get_contents($pipes[2]);
if (stripos($errorOutput, 'unable to find font') !== false) {
  trigger_error('检测到中文字体缺失，请部署Noto Sans CJK或simhei.ttf至系统字体目录', E_USER_WARNING);
}

四、Docker容器化隔离执行

该方式彻底解决Linux服务器上glibc版本冲突、字体库缺失及沙箱权限问题，尤其适用于云原生部署场景。

1、创建Dockerfile基于官方wkhtmltopdf镜像：
FROM ghcr.io/wkhtmltopdf/packaging:centos8
COPY ./src /app
RUN yum install -y fontconfig freetype && fc-cache -fv

2、在PHP中通过HTTP调用容器内API服务：
$client = new GuzzleHttp\Client();
$response = $client->post('http://wkhtmltopdf-svc:8000/convert', [
  'json' => ['html' => $htmlContent, 'options' => ['format' => 'A4']]
]);

3、响应体直接为PDF二进制流，可立即返回浏览器：
header('Content-Type: application/pdf');
header('Content-Disposition: inline; filename="document.pdf"');
echo $response->getBody();

4、关键保障：容器内预装Noto Sans CJK SC字体，并禁用外部网络访问防止XSS注入

五、mpdf作为wkhtmltopdf备选方案

当目标HTML不含复杂CSS布局或JavaScript交互，且对生成速度与内存占用敏感时，纯PHP实现的mpdf可避免外部进程依赖，提升部署一致性。

1、安装支持中文的mpdf v8.1+：
composer require mpdf/mpdf

2、初始化时指定中文字体路径与编码：
$mpdf = new \Mpdf\Mpdf([
  'mode' => 'utf-8',
  'format' => 'A4',
  'fontDir' => [__DIR__ . '/fonts'],
  'fontdata' => [
    'simsum' => ['R' => 'simsum.ttc'],
    'noto' => ['R' => 'NotoSansCJKsc-Regular.otf']
  ],
  'default_font' => 'noto'
]);

3、写入HTML前移除不兼容标签（如<script>, <canvas>）：<br>$cleanHtml = preg_replace('/<script[^>]*>.*?<\/script>/is', '', $htmlContent);<br>$mpdf->WriteHTML($cleanHtml);</script>

4、输出时强制BOM头避免Windows下乱码：
ob_start();
$mpdf->Output('report.pdf', 'S');
$pdfData = ob_get_clean();
echo "\xEF\xBB\xBF" . $pdfData;