在Laravel项目中实现图片转PDF的功能，不需要手动处理PDF的底层生成逻辑，借助社区成熟的扩展包可以快速完成需求。常用的方案是结合图片处理扩展包和PDF生成扩展包，实现从图片读取到PDF输出的完整流程。
环境准备与扩展包安装
首先需要确保项目满足基础运行环境，PHP版本建议在8.0及以上，并且安装GD库或者Imagick扩展用于处理图片。接下来安装处理PDF生成的核心扩展包，这里选择使用spatie/pdf-to-image的逆向思路，搭配barryvdh/laravel-dompdf生成PDF，同时处理图片插入逻辑。
执行以下命令安装所需扩展包：
composer require barryvdh/laravel-dompdf composer require intervention/image
安装完成后发布dompdf的配置项：
php artisan vendor:publish --provider="Barryvdh\DomPDF\ServiceProvider"
单张图片转PDF基础实现
先实现将单张图片转换为PDF的基础功能，核心思路是加载图片，将图片嵌入到HTML模板中，再通过dompdf将HTML渲染为PDF文件。
创建图片转PDF的服务类
新建一个服务类统一处理转换逻辑，避免业务逻辑和控制器耦合：
<?php
namespace App\Services;
use Intervention\Image\Facades\Image;
use Barryvdh\DomPDF\Facade\Pdf;
use Illuminate\Support\Facades\Storage;
class ImageToPdfService
{
/**
* 将单张图片转换为PDF
* @param string $imagePath 图片存储路径 如 storage/app/public/test.jpg
* @param string $outputName 输出的PDF文件名
* @return string 生成的PDF存储路径
*/
public function singleImageToPdf(string $imagePath, string $outputName): string
{
// 验证图片是否存在
if (!Storage::exists($imagePath)) {
throw new \Exception("图片文件不存在: {$imagePath}");
}
// 获取图片内容并转换为base64 避免路径引用问题
$imageContent = Storage::get($imagePath);
$imageMime = Storage::mimeType($imagePath);
$base64Image = 'data:' . $imageMime . ';base64,' . base64_encode($imageContent);
// 构建PDF的HTML内容
$html = <<<HTML
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<style>
body {
margin: 0;
padding: 0;
}
.image-container {
width: 100%;
text-align: center;
}
img {
max-width: 100%;
height: auto;
}
</style>
</head>
<body>
<div class="image-container">
<img src="{$base64Image}" alt="转换的图片">
</div>
</body>
</html>
HTML;
// 生成PDF
$pdf = Pdf::loadHTML($html);
// 设置PDF纸张为A4 纵向
$pdf->setPaper('A4', 'portrait');
// 保存PDF到存储目录
$outputPath = 'pdfs/' . $outputName;
Storage::put($outputPath, $pdf->output());
return $outputPath;
}
}控制器中调用转换方法
在控制器中接收上传的图片，调用服务类完成转换并返回结果：
<?php
namespace App\Http\Controllers;
use App\Services\ImageToPdfService;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Storage;
class PdfController extends Controller
{
public function convertImageToPdf(Request $request)
{
$request->validate([
'image' => 'required|image|mimes:jpg,jpeg,png,gif|max:20480',
]);
// 存储上传的图片
$imagePath = $request->file('image')->store('uploads/images');
$service = new ImageToPdfService();
$pdfPath = $service->singleImageToPdf($imagePath, 'output_' . time() . '.pdf');
// 返回下载链接
return response()->json([
'status' => 'success',
'pdf_url' => Storage::url($pdfPath)
]);
}
}多张图片合并转为PDF
实际场景中经常需要将多张图片合并到同一个PDF文件中，每页放置一张图片，只需要对服务类的方法做扩展即可。
<?php
namespace App\Services;
use Intervention\Image\Facades\Image;
use Barryvdh\DomPDF\Facade\Pdf;
use Illuminate\Support\Facades\Storage;
class ImageToPdfService
{
// 单张图片转换方法同上 省略
/**
* 多张图片合并转换为PDF
* @param array $imagePaths 图片路径数组
* @param string $outputName 输出的PDF文件名
* @return string 生成的PDF存储路径
*/
public function multiImageToPdf(array $imagePaths, string $outputName): string
{
$imageHtmlList = [];
foreach ($imagePaths as $imagePath) {
if (!Storage::exists($imagePath)) {
continue;
}
$imageContent = Storage::get($imagePath);
$imageMime = Storage::mimeType($imagePath);
$base64Image = 'data:' . $imageMime . ';base64,' . base64_encode($imageContent);
// 每张图片作为一页 使用page-break-after属性分页
$imageHtmlList[] = <<<HTML
<div style="page-break-after: always;">
<div style="width:100%;text-align:center;">
<img src="{$base64Image}" style="max-width:100%;height:auto;" alt="合并图片">
</div>
</div>
HTML;
}
if (empty($imageHtmlList)) {
throw new \Exception("没有有效的图片可转换为PDF");
}
$html = <<<HTML
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<style>
body { margin: 0; padding: 0; }
</style>
</head>
<body>
{$imageHtmlList[0]}
HTML;
// 拼接剩余图片页
for ($i = 1; $i < count($imageHtmlList); $i++) {
$html .= $imageHtmlList[$i];
}
$html .= <<<HTML
</body>
</html>
HTML;
$pdf = Pdf::loadHTML($html);
$pdf->setPaper('A4', 'portrait');
$outputPath = 'pdfs/' . $outputName;
Storage::put($outputPath, $pdf->output());
return $outputPath;
}
}常见问题与注意事项
- 图片尺寸问题：如果图片尺寸过大，生成的PDF可能会出现内容溢出情况，可以在转换前使用Intervention Image扩展包对图片进行缩放处理，适配A4纸张尺寸。
- 内存占用：处理大尺寸或者多张图片时，可能会占用较多内存，建议调整PHP的
memory_limit配置，或者分批处理图片。 - 特殊格式支持：dompdf对部分现代CSS属性支持有限，如果需要更复杂的排版，可以考虑使用wkhtmltopdf作为底层渲染引擎，更换对应的Laravel扩展包即可。
- 存储权限：确保storage目录有正确的写入权限，避免PDF文件无法保存的问题。
LaravelPDF_conversionimage_processingspatie_pdf修改时间：2026-06-05 15:50:06