PHP 文件上传安全实战：大小限制、MIME 检测和随机文件名

文件上传是 PHP 项目里很常见的功能：头像、附件、图片素材、导入表格都离不开它。但上传功能一旦处理粗糙，就容易出现文件过大、类型判断不准、文件名覆盖、目录暴露等问题。

本文用“用户头像上传”做例子，整理一套适合普通 Web 项目的安全处理流程：先判断上传错误，再限制大小，再用 MIME 检测真实类型，最后生成随机文件名并移动到指定目录。

摘要

本文会从最小表单开始，逐步实现 PHP 文件上传的完整后端处理。示例包含 $_FILES、UPLOAD_ERR_OK、finfo_file、random_bytes 和 move_uploaded_file 的使用方式，并补充常见坑和生产建议。

适合人群

适合正在写 PHP 表单上传、后台管理系统、用户头像、图片附件功能的开发者。你需要了解基础 PHP 数组、表单提交和文件目录权限。

目录

1. 上传表单怎么写
2. 后端先判断上传错误
3. 限制文件大小
4. 用 MIME 检测真实类型
5. 生成随机文件名并移动文件
6. 返回结果和记录日志
7. 常见问题和总结

一、上传表单怎么写

前端表单必须使用 multipart/form-data，否则 PHP 后端拿不到文件内容。

  上传头像

accept 只能改善用户选择体验，不能当作安全边界。真正的判断一定要放在后端完成。

二、后端先判断上传错误

PHP 会把上传文件放在 $_FILES 中。第一步不是移动文件，而是检查字段是否存在、上传过程是否成功。

 false, 'message' => '没有收到文件'], 400);
    return;
}

$file = $_FILES['avatar'];

if ($file['error'] !== UPLOAD_ERR_OK) {
    json_response(['ok' => false, 'message' => '上传失败，错误码：' . $file['error']], 400);
    return;
}

不要忽略 error。如果上传过程本身失败，后面的大小、类型、移动文件都没有意义。

三、限制文件大小

头像通常不需要很大。示例里限制为 2MB：

$maxBytes = 2 * 1024 * 1024;

if ($file['size']  $maxBytes) {
    json_response(['ok' => false, 'message' => '文件大小不符合要求'], 400);
    return;
}

除了业务代码中的限制，还要注意 PHP 配置项，例如 upload_max_filesize 和 post_max_size。如果配置太小，请求可能还没进入业务代码就被拦下。

四、用 MIME 检测真实类型

不能只相信用户上传的文件名后缀。更稳的做法是读取临时文件，用 finfo_file 检测 MIME 类型，然后映射到允许的扩展名。

$finfo = finfo_open(FILEINFO_MIME_TYPE);
if ($finfo === false) {
    json_response(['ok' => false, 'message' => '服务暂时不可用'], 500);
    return;
}

$mime = finfo_file($finfo, $file['tmp_name']);
finfo_close($finfo);

$allowed = [
    'image/jpeg' => 'jpg',
    'image/png' => 'png',
    'image/webp' => 'webp',
];

if (!isset($allowed[$mime])) {
    json_response(['ok' => false, 'message' => '只允许上传 JPG、PNG 或 WebP 图片'], 400);
    return;
}

$ext = $allowed[$mime];

这里不要直接使用原始文件名里的扩展名。后端根据检测结果决定扩展名，能减少伪装文件带来的风险。

五、生成随机文件名并移动文件

保存文件时，不建议使用用户原始文件名。它可能包含特殊字符，也可能和已有文件重名。可以使用随机字节生成新文件名：

$uploadDir = __DIR__ . '/uploads/avatar/' . date('Ymd');

if (!is_dir($uploadDir) && !mkdir($uploadDir, 0755, true)) {
    json_response(['ok' => false, 'message' => '上传目录创建失败'], 500);
    return;
}

$filename = bin2hex(random_bytes(16)) . '.' . $ext;
$target = $uploadDir . '/' . $filename;

if (!move_uploaded_file($file['tmp_name'], $target)) {
    json_response(['ok' => false, 'message' => '文件保存失败'], 500);
    return;
}

$publicPath = '/uploads/avatar/' . date('Ymd') . '/' . $filename;
json_response(['ok' => true, 'url' => $publicPath]);

move_uploaded_file 会确认来源是通过 HTTP POST 上传的文件，比普通文件移动更适合处理上传临时文件。

六、返回结果和记录日志

给前端的返回结果保持简单即可，例如：

{
  "ok": true,
  "url": "/uploads/avatar/20260612/9f6a1f0e8c8f4d58b1f5e3c1a2b3c4d5.webp"
}

服务端日志建议记录用户 ID、文件大小、MIME、保存路径和失败原因。不要把临时文件完整内容、用户隐私信息写进日志。

七、常见问题和总结

1. 为什么前端限制了 accept，后端还要判断

前端限制可以被绕过。后端必须自己判断文件大小和类型，不能把安全边界放在浏览器上。

2. 为什么不要保留原始文件名

原始文件名可能重复，也可能包含不适合路径的字符。随机文件名更利于避免覆盖和路径问题。

3. 上传目录要不要放在 Web 根目录

如果是图片资源，可以放在静态资源目录，但要限制可访问类型。更敏感的附件建议放在 Web 根目录之外，通过受控接口读取。

4. 图片还需要二次处理吗

头像类图片通常建议再做尺寸压缩、格式转换和重新编码，避免超大图片影响页面加载，也减少携带异常元数据的风险。

完整示例

把上面的片段合并后，核心流程就是：检查错误、限制大小、检测 MIME、生成随机名称、移动文件、返回 URL。生产项目可以再加登录态、权限、频率限制和图片压缩。

总结

PHP 文件上传看似简单，真正可靠的关键在后端：不要相信前端，不要相信原始文件名，不要只看扩展名。用 UPLOAD_ERR_OK 判断上传状态，用 finfo_file 检测真实类型，用 random_bytes 生成文件名，用 move_uploaded_file 保存文件，再配合目录隔离和日志记录，就能覆盖大多数基础上传场景。

参考资料

本文参考 PHP 官方手册中关于文件上传、move_uploaded_file 和文件信息检测函数的说明，示例为头像上传场景原创整理。