实战 php 使用 wkhtmltopdf 生成pdf的全过程

'# 实战 php 使用 wkhtmltopdf 生成pdf的全过程

一、背景与问题

在Web应用中，将网页内容转换为PDF格式是常见的需求。例如电商系统需要生成订单发票、文档系统需要导出文档内容等。传统的解决方案包括：

使用浏览器渲染后截图生成PDF（效率低、兼容性差）
使用第三方API服务（成本高、依赖外部服务）
使用wkhtmltopdf工具（开源、可定制）

本文将深入解析wkhtmltopdf的工作原理，展示在PHP项目中实现PDF生成的完整方案。特别关注其在复杂场景下的适用性、性能优化和安全注意事项。

二、基本原理

wkhtmltopdf 是基于Qt框架的开源工具，其核心原理包括：

WebKit渲染引擎：使用WebKit浏览器内核解析HTML内容
PDF生成引擎：将渲染后的页面通过PDF格式输出
命令行接口：提供标准化的命令行接口进行转换

其工作流程如下：

HTML内容 → WebKit渲染 → PDF生成 → 输出文件

关键特性：

支持CSS3、JavaScript等现代Web技术
可定制PDF页面布局（页边距、字体等）
可处理复杂的HTML结构（表格、图表等）

三、环境准备

1. 安装依赖

在Linux系统上安装：

# 安装依赖库
sudo apt-get install -y build-essential libssl-dev libxslt1-dev

# 下载wkhtmltopdf
wget https://github.com/wkhtmltopdf/wkhtmltopdf/releases/download/0.12.6/wkhtmltopdf-0.12.6-linux-x86_64.tar.xz

# 解压并设置环境变量
tar -xvf wkhtmltopdf-0.12.6-linux-x86_64.tar.xz
export PATH=$PATH:$PWD/wkhtmltopdf-0.12.6-linux-x86_64

Windows系统建议使用官方预编译版本：
https://github.com/wkhtmltopdf/wkhtmltopdf/releases

2. PHP环境配置

确保安装以下扩展：

sudo apt-get install php php-cli php-curl

四、核心实现

1. 基础PDF生成

<?php
// 基础PDF生成示例
$wkhtmltopdf = '/usr/local/bin/wkhtmltopdf'; // 指定可执行文件路径
$html = '<h1>这是PDF标题</h1><p>这是PDF正文内容</p>';
$output = 'output.pdf';

// 调用命令行生成PDF
$command = escapeshellcmd("$wkhtmltopdf --quiet - - $output");
$descriptorspec = array(
    0 => array("pipe", "r"),  // 标准输入
    1 => array("pipe", "w"),  // 标准输出
    2 => array("pipe", "w")   // 标准错误
);

$process = proc_open($command, $descriptorspec, $pipes);
if (is_resource($process)) {
    fwrite($pipes[0], $html);
    fclose($pipes[0]);
    $stdout = stream_get_contents($pipes[1]);
    fclose($pipes[1]);
    $stderr = stream_get_contents($pipes[2]);
    fclose($pipes[2]);
    proc_close($process);
}

关键点解释：

使用escapeshellcmd防止命令注入
--quiet参数抑制调试信息
--参数表示输入来自标准输入
通过proc_open实现进程控制

2. 带参数的PDF生成

<?php
// 带参数的PDF生成示例
$wkhtmltopdf = '/usr/local/bin/wkhtmltopdf';
$html = '<h1>带样式PDF</h1><p style="color:red;">这是红色文本</p>';
$output = 'styled_output.pdf';

// 设置参数
$format = '--format=A4';
$margin = '--margin-top=2cm';
$orientation = '--orientation=Portrait';

// 构建命令
$command = escapeshellcmd("$wkhtmltopdf $format $margin $orientation - - $output");
$process = proc_open($command, $descriptorspec, $pipes);
...

参数说明：

--format指定纸张大小
--margin设置页边距
--orientation设置方向
--header/--footer添加页眉页脚

3. 复杂内容处理

<?php
// 复杂内容处理示例
$wkhtmltopdf = '/usr/local/bin/wkhtmltopdf';
$html = <<<HTML
<!DOCTYPE html>
<html>
<head>
    <style>
        table { border-collapse: collapse; width: 100%; }
        th, td { border: 1px solid black; padding: 8px; }
    </style>
</head>
<body>
    <h1>复杂内容PDF</h1>
    <table>
        <tr><th>编号</th><th>名称</th></tr>
        <tr><td>1</td><td>项目A</td></tr>
        <tr><td>2</td><td>项目B</td></tr>
    </table>
</body>
</html>
HTML;

$output = 'complex_output.pdf';
$command = escapeshellcmd("$wkhtmltopdf --no-images - - $output");
$process = proc_open($command, $descriptorspec, $pipes);
...

关键点：

--no-images禁用图片加载（提高安全性）
CSS样式直接内联在HTML中
处理表格、列表等复杂结构

五、完整案例

1. 电商订单导出系统

// 电商订单导出系统（后端）
<?php
require 'vendor/autoload.php';

use Dompdf\Dompdf;

// 模拟订单数据
$order = [
    'id' => 1001,
    'items' => [
        ['name' => '商品A', 'price' => 199.00],
        ['name' => '商品B', 'price' => 299.00]
    ]
];

// 构建HTML内容
$html = <<<HTML
<!DOCTYPE html>
<html>
<head>
    <title>订单#{$order['id']}</title>
    <style>
        body { font-family: Arial, sans-serif; }
        table { width: 100%; border-collapse: collapse; }
        th, td { border: 1px solid #ccc; padding: 8px; }
    </style>
</head>
<body>
    <h1>订单详情 - #{$order['id']}</h1>
    <table>
        <tr><th>商品</th><th>价格</th></tr>
        <tr><td>{$order['items'][0]['name']}</td><td>￥{$order['items'][0]['price']}</td></tr>
        <tr><td>{$order['items'][1]['name']}</td><td>￥{$order['items'][1]['price']}</td></tr>
    </table>
</body>
</html>
HTML;

// 使用Dompdf生成PDF
$dompdf = new Dompdf();
$dompdf->loadHtml($html);
$dompdf->setPaper('A4', 'portrait');
$dompdf->render();

// 保存为文件
$dompdf->stream("order_{$order['id']}.pdf", ['Attachments' => true]);

2. 前端接口（Vue组件）

<template>
  <div>
    <button @click="exportOrder">导出订单</button>
    <a :href="pdfUrl" download="order.pdf" v-if="pdfUrl">下载PDF</a>
  </div>
</template>

<script>
export default {
  methods: {
    async exportOrder() {
      const response = await fetch('/api/order/1001/pdf');
      const blob = await response.blob();
      const url = URL.createObjectURL(blob);
      this.pdfUrl = url;
    }
  }
}
</script>

流程说明：

前端点击导出按钮
发送请求到后端API
后端生成PDF并返回
前端创建下载链接

六、源码解析

以wkhtmltopdf命令行调用为例，关键代码段：

// 命令构建
$command = escapeshellcmd("$wkhtmltopdf $format $margin $orientation - - $output");

// 进程控制
$descriptorspec = array(
    0 => array("pipe", "r"),  // 标准输入
    1 => array("pipe", "w"),  // 标准输出
    2 => array("pipe", "w")   // 标准错误
);

$process = proc_open($command, $descriptorspec, $pipes);

关键机制：

proc_open创建子进程
通过管道传递输入输出
escapeshellcmd防止命令注入
错误处理需要捕获标准错误流

七、进阶使用

1. 复杂样式支持

// 使用CSS媒体查询
$html = <<<HTML
<style>
    @media print {
        body { font-size: 12pt; }
        .no-print { display: none; }
    }
</style>
HTML;

2. 跨域资源处理

// 允许加载外部资源
$command = escapeshellcmd("$wkhtmltopdf --allow-local-doctype --enable-javascript - - output.pdf");

3. 批量处理

// 批量生成PDF
$files = glob('*.html');
foreach ($files as $file) {
    $html = file_get_contents($file);
    $output = basename($file, '.html') . '.pdf';
    $command = escapeshellcmd("$wkhtmltopdf - - $output");
    // 启动子进程处理
}

八、性能与工程实践

1. 性能优化

优化措施	效果	实现方式
缓存PDF	减少重复生成	使用Redis缓存生成结果
异步处理	提升响应速度	使用消息队列（RabbitMQ/Kafka）
资源限制	防止资源耗尽	设置最大内存、超时时间
并行处理	提升并发能力	使用多线程/多进程

2. 安全实践

安全措施	说明
输入过滤	使用白名单机制过滤HTML内容
资源隔离	限制可访问的URL范围
命令注入防护	必须使用`escapeshellcmd`
内容沙箱	使用Docker容器隔离执行环境

3. 方案比较

方案	优点	缺点
命令行调用	灵活度高	需要处理进程控制
Dompdf	无须安装依赖	功能有限
wkhtmltopdf	功能全面	需要安装环境
云服务	无须本地部署	依赖网络和API

九、常见问题与踩坑

1. 常见错误

错误现象	原因	解决办法
生成PDF为空	HTML内容未正确传递	检查`fwrite`调用
文件未生成	路径权限问题	检查文件写入权限
遇到"invalid page"	URL无效	使用`-`表示标准输入
字体缺失	系统字体库缺失	安装字体库

2. 常见陷阱

命令注入漏洞：未正确过滤用户输入参数
路径遍历漏洞：未限制输出文件路径
资源耗尽：大量并发请求导致内存溢出
格式错误：HTML结构错误导致PDF无法生成

十、最佳实践

使用现有库：推荐使用wkhtmltopdf的PHP封装库（如phpwkhtmltopdf）
参数白名单：对用户输入的参数进行白名单校验
异常处理：添加完整的错误处理逻辑
日志记录：记录生成过程中的关键信息
异步处理：将PDF生成任务放入队列处理
缓存策略：对重复请求使用缓存
安全隔离：在沙箱环境中运行生成任务

十一、总结

通过本文的深入分析，我们了解到：

wkhtmltopdf 是一个功能强大的PDF生成工具，基于WebKit引擎实现
在PHP项目中，可以通过命令行调用或现有库实现PDF生成
需要特别注意安全性、性能和错误处理
适用于需要复杂格式、动态内容的PDF生成场景
不适合对性能要求极高或需要实时生成的场景

在实际开发中，建议根据具体需求选择合适的方案。对于复杂需求，推荐使用成熟的库并配合异步处理和缓存机制。同时，必须严格防范命令注入等安全风险，确保系统稳定运行。