商城后台用PHP上传商品图片,如何校验文件类型并避免同名覆盖?
上传商品图片时,不要使用客户端提交的扩展名或 $_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



