PHP 文件上传与图片处理实战：安全校验、分片续传与对象存储

final class UploadValidator
{
    private const ALLOWED = ['image/jpeg', 'image/png', 'image/webp'];
    private const MAX_BYTES = 8 * 1024 * 1024;

    public function validate(array $file): void
    {
        if ($file['error'] !== UPLOAD_ERR_OK) {
            throw new UploadFailed('上传失败，错误码 ' . $file['error']);
        }
        if ($file['size'] > self::MAX_BYTES || !is_uploaded_file($file['tmp_name'])) {
            throw new UploadFailed('文件超限或来源非法');
        }

        $mime = (new \finfo(FILEINFO_MIME_TYPE))->file($file['tmp_name']);
        if (!in_array($mime, self::ALLOWED, true)) {
            throw new UploadFailed("不支持的类型：{$mime}");
        }
        if (@getimagesize($file['tmp_name']) === false) {  // 真实图片结构校验
            throw new UploadFailed('文件不是有效图片');
        }
    }
}

[$w, $h] = getimagesize($tmp);
if ($w * $h > 40_000_000) {          // 4000 万像素上限
    throw new UploadFailed('图片尺寸过大');
}

# 上传目录禁止执行脚本
location ^~ /uploads/ {
    location ~ \.(php|phtml|phar)$ { deny all; }
}

$ext  = match ($mime) {                 // 由服务端判定，而非客户端
    'image/jpeg' => 'jpg', 'image/png' => 'png', 'image/webp' => 'webp',
};
$name = bin2hex(random_bytes(16)) . '.' . $ext;
$path = sprintf('uploads/%s/%s/%s', date('Y/m'), substr($name, 0, 2), $name);

① POST /upload/init → 返回 uploadId   ② PUT /upload/{id}/part/{n} → 上传分片（可并发）
③ GET /upload/{id} → 查询已上传分片   ④ POST /upload/{id}/complete → 合并并校验整体哈希

// ② 接收分片：先落临时目录，记录已完成分片
$key = sprintf('chunks/%s/%d', $uploadId, $partNumber);
$storage->writeStream($key, fopen($tmp, 'rb'));
$redis->sadd("upload:{$uploadId}:parts", (string) $partNumber);

$parts = $this->redis->smembers("upload:{$uploadId}:parts");
sort($parts, SORT_NUMERIC);
if (count($parts) !== $expectedCount) { throw new UploadFailed('分片不完整'); }

$hash = $storage->mergeChunks($uploadId, $parts, $finalKey);
if (!hash_equals($declaredSha256, $hash)) {      // 整体一致性校验
    throw new UploadFailed('文件哈希不匹配，请重传');
}

$s3  = new Aws\S3\S3Client(['region' => 'cn-north-1', 'version' => 'latest']);
$cmd = $s3->getCommand('PutObject', [
    'Bucket' => 'user-uploads', 'Key' => $key, 'ContentType' => $mime,
]);

$url = (string) $s3->createPresignedRequest($cmd, '+10 minutes')->getUri();
// 返回给客户端，由客户端直接 PUT 上传

$policy = [
    'expiration' => gmdate('c', time() + 600),
    'conditions' => [
        ['content-length-range', 0, 8 * 1024 * 1024],   // 大小上限
        ['starts-with', '$key', "uploads/{$userId}/"],   // 路径前缀隔离
        ['eq', '$Content-Type', 'image/jpeg'],
    ],
];

$head = $s3->headObject(['Bucket' => $bucket, 'Key' => $key]);
if ($head['ContentLength'] > 8 * 1024 * 1024 || $head['ContentType'] !== 'image/jpeg') {
    $s3->deleteObject(['Bucket' => $bucket, 'Key' => $key]);   // 不合法立即清理
    throw new UploadFailed('直传文件校验失败');
}

$src   = imagecreatefromstring(file_get_contents($tmp));   // 自动识别格式
$ratio = min($maxW / imagesx($src), $maxH / imagesy($src), 1);   // 只缩不放
$dst   = imagescale($src, (int) round(imagesx($src) * $ratio), (int) round(imagesy($src) * $ratio));

imagejpeg($dst, $outPath, 82);   // 质量 82 是体积与观感的平衡点
imagedestroy($src);
imagedestroy($dst);

$img = new Imagick($tmp);
$img->autoOrient();                       // 按 EXIF 方向校正，手机照片必做
$img->thumbnailImage(1200, 1200, true);   // 保持比例
$img->setImageFormat('webp');
$img->setImageCompressionQuality(80);
$img->stripImage();                       // 清除 EXIF（含 GPS 隐私）
$img->writeImage($outPath);

$logo = imagescale(imagecreatefrompng(__DIR__ . '/watermark.png'), (int) (imagesx($dst) * 0.15));
imagecopy($dst, $logo, imagesx($dst) - imagesx($logo) - 8, imagesy($dst) - imagesy($logo) - 8,
    0, 0, imagesx($logo), imagesy($logo));

// 控制器：只做校验 + 落原始文件 + 派发任务
$validator->validate($file);
$key = $storage->put($file['tmp_name']);
ProcessImage::dispatch($key, $userId);          // 202 Accepted，不阻塞请求

// 队列任务：解码、缩放、生成多尺寸、写回元数据
final class ProcessImage implements ShouldQueue
{
    public int $tries = 3;
    public int $timeout = 120;

    public function handle(ImageProcessor $processor): void
    {
        $processor->generateVariants($this->key);
        ImageAsset::where('key', $this->key)->update(['status' => 'ready']);
    }
}