前置需求
- 安裝 ImageMagick:`apt-get install imagemagick` / `brew install imagemagick`
- 安裝 PHP 擴展:`pecl install imagick` 或 `apt-get install php-imagick`
- 驗證:`php -m | grep imagick`、`php -r 'phpinfo();' | grep imagick`
- 策略檔權限:`/etc/ImageMagick-6/policy.xml` 需允許 PDF 讀取 (``)
方法一:指定頁碼讀取 (適合單頁/首頁縮圖)
<?php
/**
* PDF 指定頁面轉 PNG 縮圖
* @param string $pdfPath PDF 檔案路徑
* @param string $outDir 輸出目錄
* @param int $page 頁碼 (0=第一頁, -1=所有頁)
* @param int $width 縮圖寬度
* @param int $height 縮圖高度
* @return string|array|false 成功回傳檔案路徑,失敗 false
*/
function pdfToPng(string $pdfPath, string $outDir, int $page = 0, int $width = 200, int $height = 150): string|array|false {
if (!extension_loaded('imagick')) {
error_log('Imagick extension not loaded');
return false;
}
if (!is_file($pdfPath)) {
error_log("PDF not found: $pdfPath");
return false;
}
if (!is_dir($outDir) && !mkdir($outDir, 0755, true)) {
error_log("Cannot create output dir: $outDir");
return false;
}
try {
$im = new Imagick();
$im->setResolution(150, 150); // 解析度 DPI,影響清晰度
$im->setCompressionQuality(85); // JPEG/PNG 品質 0-100
$im->readImage($pdfPath . "[$page]"); // 關鍵:[0] 讀第一頁
// 縮放模式:保持比例
$im->thumbnailImage($width, $height, true, true);
// 去除透明背景 (可選)
$im->setImageBackgroundColor('white');
$im->setImageAlphaChannel(Imagick::ALPHACHANNEL_REMOVE);
$im->mergeImageLayers(Imagick::LAYERMETHOD_FLATTEN);
$filename = $outDir . '/' . basename($pdfPath, '.pdf') . '_page' . ($page+1) . '_' . time() . '.png';
if ($im->writeImage($filename)) {
$im->clear();
$im->destroy();
return $filename;
}
return false;
} catch (ImagickException $e) {
error_log("Imagick error: " . $e->getMessage());
return false;
}
}
// 使用
$thumb = pdfToPng('documents/report.pdf', 'thumbnails', 0, 300, 200);
if ($thumb) echo "<img src='$thumb'>";
方法二:逐頁迭代轉換 (適合多頁文檔全轉圖)
<?php
/**
* PDF 所有頁面轉 PNG 陣列
* @return string[]|false 成功回傳檔案路徑陣列
*/
function pdfToPngAll(string $pdfPath, string $outDir, int $width = 800, int $height = 0): array|false {
if (!extension_loaded('imagick') || !is_file($pdfPath)) return false;
if (!is_dir($outDir) && !mkdir($outDir, 0755, true)) return false;
try {
$im = new Imagick();
$im->setResolution(150, 150);
$im->setCompressionQuality(90);
$im->readImage($pdfPath); // 讀取全部頁面
$results = [];
foreach ($im as $index => $frame) {
// 每頁獨立處理
$frame->setImageFormat('png');
$frame->thumbnailImage($width, $height, true, true);
$frame->setImageBackgroundColor('white');
$frame->mergeImageLayers(Imagick::LAYERMETHOD_FLATTEN);
$filename = $outDir . '/' . basename($pdfPath, '.pdf') . '_p' . ($index+1) . '_' . md5($frame->getImageSignature()) . '.png';
if ($frame->writeImage($filename)) {
$results[] = $filename;
}
}
$im->clear();
$im->destroy();
return $results ?: false;
} catch (ImagickException $e) {
error_log("Imagick error: " . $e->getMessage());
return false;
}
}
// 使用
$thumbs = pdfToPngAll('documents/manual.pdf', 'thumbnails', 1024);
if ($thumbs) {
foreach ($thumbs as $t) echo "<img src='$t' style='max-width:300px'>";
}
關鍵參數詳細說明
| 方法 | 用途 | 建議值 |
| setResolution(x, y) | 渲染解析度 (DPI) | 150-300 (螢幕 72, 列印 300) |
| setCompressionQuality(q) | 輸出品質 | 80-95 (PNG 無損但影響壓縮速度) |
| readImage("file.pdf[0]") | 讀取指定頁 (0-based) | 單頁模式關鍵 |
| thumbnailImage(w, h, true, true) | 等比縮放、縮小不放大 | 最佳縮圖方法 |
| scaleImage(w, h, true) | 強制尺寸 (可能變形) | 需固定尺寸時 |
| setImageBackgroundColor | 透明背景填充色 | 'white' 或 '#FFFFFF' |
| mergeImageLayers(FLATTEN) | 合併圖層移除透明 | 配合背景色使用 |
效能優化策略
- 降低解析度:縮圖用 72-150 DPI 即可,300 DPI 僅供列印級
- 限制記憶體:`$im->setResourceLimit(Imagick::RESOURCETYPE_MEMORY, 256 * 1024 * 1024)` (256MB)
- 使用臨時檔:`$im->setResourceLimit(Imagick::RESOURCETYPE_DISK, 1024 * 1024 * 1024)` (1GB 磁碟快取)
- 平行處理:多 PDF 同時轉換用 `pcntl_fork` 或佇列工作者
- 快取縮圖:以 PDF 檔案 hash + 頁碼 + 尺寸為 key 存 Redis/檔案
常見錯誤與解決
| 錯誤 | 原因 | 解決 |
| PDFDelegateFailed | Ghostscript 未安裝或 policy.xml 禁止 PDF | 安裝 gs;修改 policy.xml 允許 PDF |
| Unable to open image | 路徑錯誤、權限不足、檔案損壞 | 檢查 realpath、chmod 644 |
| Memory allocation failed | 大 PDF 解析超過 memory_limit | 調高 php.ini memory_limit、Imagick resource limit |
| 輸出全黑/空白 | 色彩空間 CMYK、透明層疊加 | setImageColorSpace(sRGB)、flatten |
| 中文檔名亂碼 | 檔案系統編碼問題 | 用 md5/時間戳命名、urlencode |
替代方案:無 Imagick 環境
<?php
// 方案 1:呼叫系統指令 (需安裝 poppler-utils: pdftoppm)
function pdfToPpm(string $pdf, string $outDir, int $page = 1): string|false {
$outPrefix = $outDir . '/' . basename($pdf, '.pdf');
$cmd = "pdptoppm -png -f $page -l $page -scale-to 800 " . escapeshellarg($pdf) . ' ' . escapeshellarg($outPrefix);
exec($cmd . ' 2>&1', $output, $code);
if ($code === 0 && ($file = glob($outPrefix . '*.png')[0] ?? null)) return $file;
return false;
}
// 方案 2:使用 spatie/pdf-to-image (Composer 套件,內部封裝 Imagick/pdftoppm)
/*
composer require spatie/pdf-to-image
use Spatie\PdfToImage\Pdf;
$pdf = new Pdf($pdfPath);
$pdf->saveImage($outPath); // 預設第一頁
$pdf->getAllPages()->saveImages($outDir); // 所有頁
*/
安全性提醒
- **嚴格驗證上傳檔案**:MIME、副檔名、檔案頭 (magic bytes `%PDF`)
- **限制檔案大小**:`ini_set('upload_max_filesize', '10M')`
- **隔離執行環境**:容器化、禁用網路、唯讀根目錄
- **清理臨時檔**:`register_shutdown_function` 確保刪除
Imagick 是 PHP 處理 PDF 轉圖的標準選擇,掌握兩種讀取模式與關鍵參數,即可穩定產出高品質縮圖。
copyright ©
萬盛學電腦網 all rights reserved