Laravel大文件上传时Jobs表无队列数据插入问题排查

问题描述 #

• 表单支持多图上传，单图大小1-2MB，引入Laravel队列实现后台上传以优化前端请求耗时
• 小图片上传流程正常；大图片请求pending许久后返回201状态码，Trip基础数据成功入库，但Image表无图片记录
• 核心异常：Jobs表和failed_jobs表均无队列任务插入，且已确认php artisan queue:work命令处于运行状态

原因分析 #

1. 大文件base64编码导致Payload超限：base64编码会使文件体积膨胀约33%，1-2MB的图片会变成1.3-2.6MB，多图场景下总数据量会超过Laravel database队列默认的payload字段容量（默认text类型仅支持最大64KB存储），导致任务无法写入Jobs表，直接静默失败。
2. 控制器同步处理大文件拖慢请求：在控制器中对大文件执行file_get_contents和base64_encode是同步操作，不仅违背了用队列优化耗时的初衷，还可能触发PHP内存限制或请求超时，导致任务分发前就异常终止。

解决方案 #

1. 避免在控制器中处理大文件编码 #

直接传递上传文件的临时路径给队列任务，跳过base64编解码步骤，大幅减少内存占用和数据传输量。

2. 调整队列数据库字段容量（可选） #

若业务需要传递较大Payload，将Jobs表的payload字段从text改为longtext（支持最大4GB存储）。

3. 优化队列任务中的文件处理逻辑 #

直接操作临时文件，可结合图片处理库完成格式转换（如转为webp压缩体积）。

代码修正示例 #

修正后的TripController

public function create(TripRequest $tripRequest)
{
    $validatedData = $tripRequest->validated();

    $trip = Trip::create([
        'title' => $validatedData['title'],
        'description' => $validatedData['description'],
        'trip_type' => $validatedData['trip_type'],
        'address' => $validatedData['address'],
        'user_id' => auth()->user()->id,
    ]);

    // 直接传递上传文件的临时路径，而非编码后的字符串
    $imagePaths = array_map(function ($image) {
        return $image->getRealPath();
    }, $validatedData['images']);

    UploadImagesProcess::dispatch($trip->id, $imagePaths);

    return new JsonResponse($trip, JsonResponse::HTTP_CREATED);
}

修正后的UploadImagesProcess Job

<?php

namespace App\Jobs;

use App\Models\Trip;
use App\Models\Image;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;
use Illuminate\Support\Facades\Storage;
use Illuminate\Support\Facades\Image as InterventionImage;

class UploadImagesProcess implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public function __construct(public $tripId, public $imagePaths)
    {
    }

    public function handle(): void
    {
        $trip = Trip::findOrFail($this->tripId);

        foreach ($this->imagePaths as $imagePath) {
            // 直接读取临时文件并转换为webp格式（质量80可按需调整）
            $image = InterventionImage::make($imagePath);
            $image->encode('webp', 80);

            $filename = uniqid() . '.webp';
            $filePath = 'images/trips/' . $filename;

            // 存储到public磁盘
            Storage::disk('public')->put($filePath, $image);

            // 关联保存图片记录
            $trip->images()->create([
                'image_url' => '/' . $filePath,
                'image_for' => 'trip',
            ]);
        }
    }
}

额外注意事项 #

• 若使用图片格式转换，需先安装Intervention Image库：composer require intervention/image
• 如需调整队列Payload字段容量，生成迁移文件修改Jobs表：

Schema::table('jobs', function (Blueprint $table) {
    $table->longText('payload')->change();
});

执行迁移：php artisan migrate

• 检查php.ini配置中的upload_max_filesize和post_max_size，确保数值大于单图大小，避免上传时文件被截断

内容的提问来源于stack exchange，提问作者moemen saadeh