直接 composer require php-wkhtmltopdf 会失败，因为它不是 packagist 官方包，仅是系统命令封装；第三方 fork 如 nickcv/php-wkhtmltopdf 已多年未维护且不兼容 php 8.1+；应改用持续维护、支持 php 8+ 的 knplabs/knp-snappy，并正确配置 wkhtmltoimage 路径、格式、dpi、超时等参数。
为什么直接 composer require 会失败
因为 php-wkhtmltopdf 本身不是 Composer 可安装的包——它只是对系统命令 wkhtmltopdf 或 wkhtmltoimage 的 PHP 封装，没有官方 Packagist 发布版本。你搜到的 nickcv/php-wkhtmltopdf 等第三方 fork 多年未维护，且依赖过时的 symfony/process v2/v3，PHP 8.1+ 下会报 ArgumentCountError 或找不到 ProcessBuilder 类。
正确做法：用 knplabs/knp-snappy 替代
这是目前最稳定、持续维护、支持 PHP 8+ 的替代方案，底层同样调用系统 wkhtmltopdf/wkhtmltoimage，但封装更健壮，API 清晰。
- 运行
composer require knplabs/knp-snappy - 确保系统已安装
wkhtmltoimage（注意不是 pdf 版本）：wkhtmltoimage --version能正常输出 - Linux/macOS 下建议用静态编译版（如 wkhtmltopdf.org 官方打包版），避免 Qt 库缺失导致 segfault
- Windows 用户需把
wkhtmltoimage.exe路径加入环境变量，或在构造时显式指定：new PdfGenerator('C:/bin/wkhtmltoimage.exe')
生成图片的关键参数和坑
wkhtmltoimage 默认输出 PDF，要出 PNG/JPEG 必须显式指定格式和质量参数，否则会静默失败或返回空内容。
- 设置输出格式：
$snappy->setOption('format', 'png') - 指定 DPI 提升清晰度（默认 96，网页常模糊）：
$snappy->setOption('quality', 100)和$snappy->setOption('dpi', 144) - 禁用智能缩放（否则小图可能被拉伸）：
$snappy->setOption('zoom', 1) - 超时时间容易被忽略：
$snappy->setTimeout(30)，否则大页面卡住会阻塞 PHP 进程 - 如果页面含 HTTPS 资源但证书不被信任，加：
$snappy->setOption('ssl-protocol', 'TLSv1.2')和$snappy->setOption('no-stop-slow-scripts', true)
实际调用示例（带错误判断）
$snappy = new \Knp\Snappy\Image('wkhtmltoimage');
$snappy->setOption('format', 'png');
$snappy->setOption('dpi', 144);
$snappy->setOption('quality', 100);
try {
$output = $snappy->getOutput('https://example.com');
file_put_contents('/tmp/screenshot.png', $output);
} catch (\Knp\Snappy\Exception\RuntimeException $e) {
// 常见错误：'Exit with code 1 due to network error: HostNotFoundError'
// 或 'Unable to write to destination' —— 检查路径权限和磁盘空间
error_log($e->getMessage());
}
注意：getOutput() 返回的是原始二进制数据，不是 base64；保存前别用 json_encode 或 echo 直接输出，会破坏图片头信息。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
