商城后台用PHP上传商品图片,如何校验文件类型并避免同名覆盖?

发布人:A5数据发布时间:2026-11-17 10:56阅读量:1

上传商品图片时,不要使用客户端提交的扩展名或 $_FILES['type'] 作为判断依据,也不要直接用原始文件名拼接保存路径。更稳妥的做法是:服务端读取临时文件,用 fileinfo 和 getimagesize() 双重确认图片类型,再按照检测出的 MIME 类型生成随机文件名,并以独占创建方式写入存储目录。

下面给出一个 PHP 8.1 及以上可使用的实现,默认允许 JPEG、PNG 和 WebP,单个文件限制为 5 MiB。存储目录应配置在网站可访问目录之外,原始文件名只保存为展示信息,不参与物理文件路径生成。

先确定校验和命名规则配图

先确定校验和命名规则

检查或处理项实现方式目的
上传状态检查 UPLOAD_ERR_*区分超限、未上传完成和临时目录错误
文件来源is_uploaded_file()确认文件来自 HTTP 上传
文件大小读取临时文件实际大小避免只依赖客户端提交的数据
文件类型finfo_file() 检测 MIME不信任文件扩展名和客户端 MIME
图片结构getimagesize() 读取尺寸并比对 MIME排除仅修改扩展名的非图片文件
保存名称random_bytes() 生成随机名称允许多个文件使用相同原始名称
防覆盖使用 fopen(..., 'xb') 独占创建目标文件已存在时创建失败,不覆盖旧文件

fileinfo 扩展需要处于启用状态。代码不使用 Composer 依赖,getimagesize() 也是 PHP 提供的图片信息读取函数。

如果应用限制为 5 MiB,PHP 的请求限制也不能低于这个范围。例如,可以在配置中设置为:

upload_max_filesize = 6M
post_max_size = 7M

post_max_size 限制的是整个 POST 请求,还需要为表单字段和其他请求数据预留空间。

PHP实现:校验后以独占方式写入

将下面的函数放入例如 ProductImageUploader.php 文件中。它不会使用原始文件名保存文件,而是按照实际检测出的类型生成 .jpg、.png 或 .webp 后缀。

<?php
declare(strict_types=1);

/**
 * 保存后台上传的商品图片。
 *
 * @param array  $file        $_FILES['product_image'] 对应的数组
 * @param string $storageDir  网站公开目录之外的存储目录
 * @param int    $maxBytes    单文件最大字节数
 *
 * @return array{
 *     stored_name: string,
 *     original_name: string,
 *     mime: string,
 *     size_bytes: int,
 *     width: int,
 *     height: int
 * }
 */
function saveProductImage(
    array $file,
    string $storageDir,
    int $maxBytes = 5 * 1024 * 1024
): array {
    if ($maxBytes <= 0) {
        throw new InvalidArgumentException('文件大小限制配置无效');
    }

    if (!isset($file['error'], $file['tmp_name'])) {
        throw new InvalidArgumentException('未找到上传文件');
    }

    $error = (int) $file['error'];

    $errorMessages = [
        UPLOAD_ERR_INI_SIZE   => '文件超过服务器允许的上传大小',
        UPLOAD_ERR_FORM_SIZE  => '文件超过表单允许的大小',
        UPLOAD_ERR_PARTIAL    => '文件上传未完成',
        UPLOAD_ERR_NO_FILE    => '请选择商品图片',
        UPLOAD_ERR_NO_TMP_DIR => '服务器临时目录不可用',
        UPLOAD_ERR_CANT_WRITE => '服务器无法写入上传文件',
        UPLOAD_ERR_EXTENSION  => '上传被服务器扩展中止',
    ];

    if ($error !== UPLOAD_ERR_OK) {
        throw new RuntimeException(
            $errorMessages[$error] ?? '文件上传失败'
        );
    }

    $tmpName = $file['tmp_name'];

    if (!is_string($tmpName) || !is_uploaded_file($tmpName)) {
        throw new RuntimeException('上传文件来源无效');
    }

    $actualSize = filesize($tmpName);

    if ($actualSize === false || $actualSize <= 0) {
        throw new RuntimeException('无法读取上传文件');
    }

    if ($actualSize > $maxBytes) {
        $maxMiB = number_format($maxBytes / 1024 / 1024, 1);
        throw new RuntimeException("图片不能超过 {$maxMiB} MiB");
    }

    /*
     * 只允许栅格图片。
     * SVG 可能包含脚本或外部资源,不在这里直接接收。
     */
    $allowedMimeTypes = [
        'image/jpeg' => 'jpg',
        'image/png'  => 'png',
        'image/webp' => 'webp',
    ];

    $finfo = finfo_open(FILEINFO_MIME_TYPE);

    if ($finfo === false) {
        throw new RuntimeException('服务器未启用 fileinfo 扩展');
    }

    $mime = finfo_file($finfo, $tmpName);
    finfo_close($finfo);

    if (!is_string($mime) || !isset($allowedMimeTypes[$mime])) {
        throw new RuntimeException('只支持 JPEG、PNG 或 WebP 图片');
    }

    /*
     * getimagesize() 用于确认文件具备可识别的图片结构,
     * 并检查它返回的 MIME 是否与 fileinfo 检测结果一致。
     */
    $imageInfo = @getimagesize($tmpName);

    if (
        $imageInfo === false ||
        ($imageInfo['mime'] ?? '') !== $mime
    ) {
        throw new RuntimeException('文件内容不是有效的商品图片');
    }

    $width = (int) ($imageInfo[0] ?? 0);
    $height = (int) ($imageInfo[1] ?? 0);

    // 限制尺寸,避免后续生成缩略图时处理超大图片。
    if (
        $width < 1 ||
        $height < 1 ||
        $width > 8000 ||
        $height > 8000 ||
        $width * $height > 40_000_000
    ) {
        throw new RuntimeException('图片尺寸超出允许范围');
    }

    /*
     * 这里只保存原始名称作为元数据。
     * 它不参与路径拼接,也不用于生成存储文件名。
     */
    $originalName = isset($file['name']) && is_string($file['name'])
        ? $file['name']
        : '';

    if (!is_dir($storageDir)) {
        if (!mkdir($storageDir, 0750, true) && !is_dir($storageDir)) {
            throw new RuntimeException('无法创建图片存储目录');
        }
    }

    if (!is_writable($storageDir)) {
        throw new RuntimeException('图片存储目录不可写');
    }

    $targetPath = null;
    $output = false;
    $extension = $allowedMimeTypes[$mime];

    /*
     * x 模式要求目标文件不存在。
     * 即使极小概率发生随机名称冲突,也会重新生成名称,而不是覆盖旧文件。
     */
    for ($attempt = 0; $attempt < 5; $attempt++) {
        $storedName = bin2hex(random_bytes(16)) . '.' . $extension;
        $candidate = $storageDir . DIRECTORY_SEPARATOR . $storedName;

        $output = @fopen($candidate, 'xb');

        if ($output !== false) {
            $targetPath = $candidate;
            break;
        }
    }

    if ($output === false || $targetPath === null) {
        throw new RuntimeException('无法创建唯一的图片存储文件');
    }

    $input = null;

    try {
        $input = fopen($tmpName, 'rb');

        if ($input === false) {
            throw new RuntimeException('无法读取上传临时文件');
        }

        $copiedBytes = stream_copy_to_stream($input, $output);

        if ($copiedBytes !== $actualSize || !fflush($output)) {
            throw new RuntimeException('图片写入不完整');
        }

        fclose($input);
        $input = null;

        fclose($output);
        $output = null;
    } catch (Throwable $e) {
        if (is_resource($input)) {
            fclose($input);
        }

        if (is_resource($output)) {
            fclose($output);
        }

        if (is_string($targetPath)) {
            @unlink($targetPath);
        }

        throw $e;
    }

    return [
        'stored_name'   => $storedName,
        'original_name' => $originalName,
        'mime'          => $mime,
        'size_bytes'    => $actualSize,
        'width'         => $width,
        'height'        => $height,
    ];
}

这里没有调用 move_uploaded_file(),而是先用 fopen($path, 'xb') 创建目标文件,再把上传临时文件的内容复制进去。xb 中的 x 表示目标必须不存在,因此不会因为名称冲突而覆盖已有文件。

在后台接口中调用

表单需要使用 multipart/form-data,文件字段名称与接口中读取的 product_image 保持一致:

<form
    action="/admin/product-image-upload.php"
    method="post"
    enctype="multipart/form-data"
>
    <label for="product-image">商品图片</label>
    <input
        id="product-image"
        type="file"
        name="product_image"
        accept="image/jpeg,image/png,image/webp"
        required
    >

    <button type="submit">上传图片</button>
</form>

accept 只用于改善后台页面的选择体验,不能替代服务端校验。接口文件中先执行现有后台的登录、权限和 CSRF 校验,再调用保存函数:

<?php
declare(strict_types=1);

require_once __DIR__ . '/ProductImageUploader.php';

// 这里应先执行现有后台的登录、权限和 CSRF 校验。
if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
    http_response_code(405);
    exit('只允许使用 POST 请求');
}

/*
 * 该目录只是示例,实际应通过配置指定到网站公开目录之外。
 * 不要让请求参数直接决定 storageDir。
 */
$storageDir = '/srv/shop-storage/product-images';

try {
    $image = saveProductImage(
        $_FILES['product_image'] ?? [],
        $storageDir
    );

    /*
     * 在这里写入商品图片表,例如保存:
     * - stored_name:实际存储名
     * - original_name:后台展示用的原始名
     * - mime:服务端检测出的 MIME
     * - size_bytes、width、height
     *
     * 如果数据库写入失败,应删除刚创建的文件,
     * 或先写入 pending 状态,待数据库记录成功后再标记为 active。
     */

    header('Content-Type: application/json; charset=utf-8');
    http_response_code(201);

    echo json_encode(
        [
            'ok'    => true,
            'image' => $image,
        ],
        JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR
    );
} catch (InvalidArgumentException | RuntimeException $e) {
    http_response_code(422);
    header('Content-Type: application/json; charset=utf-8');

    echo json_encode(
        [
            'ok'      => false,
            'message' => $e->getMessage(),
        ],
        JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR
    );
}

如果接口位于 /public/admin/ 下,/srv/shop-storage/product-images 这类目录可以放在网站根目录之外。需要对外展示图片时,可以由现有图片读取接口输出,或者配置一个只允许读取图片、禁止脚本执行的静态目录。

不同输入下的处理结果配图

A5数据提供香港、美国、日本等地区的物理服务器租用,建站类配置可选SSD或NVMe存储,也有面向大容量文件需求的机械硬盘方案。不同地区和产品系列的CPU、内存、磁盘及网络配置各有差异,可为运行PHP后台和存放商品图片的业务环境提供硬件选择。

不同输入下的处理结果

  • 上传名为 summer.jpg、内容确实为 JPEG 的文件:保存为随机生成的 .jpg 文件,原始名称单独记录。
  • 再上传一个同样名为 summer.jpg 的文件:生成另一个随机名称,前一个文件不会被覆盖。
  • 将 PHP 文件改名为 cover.jpg:fileinfo 检测到的 MIME 通常不是允许的图片类型,上传被拒绝。
  • 文件名是 cover.jpg,但实际内容是 PNG:通过检测后会按 image/png 保存为随机的 .png 文件,而不是沿用错误的 .jpg 后缀。
  • 上传 SVG:默认被拒绝。若业务确实需要 SVG,应先进行专门的 XML 清理和内容策略控制,不能仅依靠扩展名判断。

随机名称应保存到数据库的 stored_name 字段,并可以为该字段增加唯一索引;original_name 不应设置为唯一字段,否则两个商品都上传 banner.jpg 时会产生不必要的冲突。若后续还要生成缩略图,建议在尺寸限制之后使用图像库重新解码并编码,减少原始文件中额外内容带来的风险。

不同输入下的处理结果配图

本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/9938.html

相关推荐