PHP 文件上传如何同时限制扩展名、MIME 与文件大小

PHP 文件上传要同时限制扩展名、MIME 与文件大小，核心做法不是写三个互不相关的判断，而是建立一份扩展名到 MIME 的成对白名单，并在文件进入永久目录前完成四步检查：先确认上传错误码，再检查服务端收到的字节数，然后读取原始文件名的扩展名，最后使用 Fileinfo 从临时文件内容识别 MIME。四步全部通过，才生成随机文件名并调用 move_uploaded_file()。

PHP 文件上传官方文档：https://www.php.net/manual/en/features.file-upload.post-method.php

扩展名描述用户提交的名称，MIME 是服务器对临时文件内容的识别结果，文件大小控制资源占用。三者解决的问题不同，任何一个都不能替代另外两个。

项目目标与处理边界

这个小项目接收一个名为 document 的表单文件，允许 JPEG、PNG 和 PDF，单文件最大 5 MiB。处理器只负责“是否接收以及保存到哪里”，不会把客户端的 accept 属性或 Content-Type 请求头当成可信结论，也不会宣称这些检查能够代替恶意文件扫描。

目标目录最好放在 Web 根目录之外。如果业务必须让用户下载文件，应由应用根据业务权限读取并输出，而不是让上传目录直接暴露为可执行或可遍历的静态目录。本文返回的是随机存储名，原始文件名只用于提取扩展名，不参与最终路径拼接。

环境准备：先处理 PHP 的前置限制

应用代码中的 5 MiB 是最终业务规则，但 PHP 在代码运行前还有 post_max_size 与 upload_max_filesize。这两个配置不能小于业务上限，否则请求可能在进入处理器前就被截断。还应确认 file_uploads 已开启、临时目录可用，并启用了 Fileinfo 扩展。

表单必须使用 POST 和 multipart/form-data：

  
  上传

accept 不是安全边界，用户可以绕过页面直接构造请求；上传处理器仍须完整执行服务端检查。

三种限制各自解决什么问题

白名单必须成对配置。例如 jpg 和 jpeg 只允许对应 image/jpeg，png 对应 image/png，pdf 对应 application/pdf。如果只维护“允许的扩展名列表”和“允许的 MIME 列表”，攻击者可能让两个列表分别通过，但扩展名与 MIME 实际上并不匹配。

核心代码：按固定顺序完成四层检查

 ['image/jpeg'],
        'jpeg' => ['image/jpeg'],
        'png'  => ['image/png'],
        'pdf'  => ['application/pdf'],
    ];

    // 先验证上传结构，避免把数组值或缺失字段继续传入文件函数
    if (!isset($file['error'], $file['tmp_name'], $file['name'], $file['size'])
        || is_array($file['error'])) {
        throw new RuntimeException('上传参数结构不完整');
    }

    // UPLOAD_ERR_OK 表示 PHP 上传阶段没有报告错误
    if ($file['error'] !== UPLOAD_ERR_OK) {
        throw new RuntimeException('上传失败，错误码：' . (int) $file['error']);
    }

    // 对服务端收到的字节数执行明确的业务限制
    $size = (int) $file['size'];
    if ($size  $maxBytes) {
        throw new RuntimeException('文件必须大于 0 且不超过 5 MiB');
    }

    // 原始文件名仅用于提取并规范化扩展名，不参与目标路径拼接
    $extension = strtolower(pathinfo((string) $file['name'], PATHINFO_EXTENSION));
    if (!isset($allowed[$extension])) {
        throw new RuntimeException('不允许的文件扩展名');
    }

    // Fileinfo 从临时文件内容识别 MIME，不信任客户端 Content-Type
    $finfo = new finfo(FILEINFO_MIME_TYPE);
    $mime = $finfo->file((string) $file['tmp_name']);
    if (!is_string($mime) || !in_array($mime, $allowed[$extension], true)) {
        throw new RuntimeException('文件扩展名与内容类型不匹配');
    }

    // 保存前确认目标目录已由部署流程创建并且当前进程可写
    if (!is_dir($targetDir) || !is_writable($targetDir)) {
        throw new RuntimeException('上传目录不存在或不可写');
    }

    // 随机文件名隔离用户输入，并避免可预测路径
    $storedName = bin2hex(random_bytes(16)) . '.' . $extension;
    $target = rtrim($targetDir, DIRECTORY_SEPARATOR)
        . DIRECTORY_SEPARATOR . $storedName;

    // 防御性拒绝意外重名，不覆盖已有文件
    if (file_exists($target)) {
        throw new RuntimeException('目标文件名冲突，请重试');
    }

    // 仅移动 PHP 确认过的 HTTP POST 上传文件
    if (!move_uploaded_file((string) $file['tmp_name'], $target)) {
        throw new RuntimeException('文件保存失败');
    }

    return $storedName;
}

顺序很重要。先处理 error，可以避免对未完成上传的临时文件做后续判断；大小检查应尽早执行，减少无效的内容识别；扩展名先进入白名单后，再用它找到允许的 MIME 集合；最后只有成对匹配成功才进入持久化阶段。

接入处理器并返回可控结果

getMessage(), ENT_QUOTES, 'UTF-8');
}

如果还要保存原始文件名，应把它作为普通业务字段处理：限制长度、统一字符编码，并在输出页面时转义。不要用原始文件名构造磁盘路径，也不要根据它决定文件是否可以执行。

保存时不要继续使用原始文件名

move_uploaded_file() 会确认源文件是有效的 HTTP POST 上传文件；失败时返回 false。它仍然可能覆盖已存在的目标文件，所以代码在移动前检查目标路径，同时采用 128 位随机名称把冲突概率降到极低。目录创建和权限设置应由部署流程负责，而不是根据请求临时开放宽泛权限。

图片类业务如果需要更强的一致性，还可以在白名单通过后使用图像解码库重新读取并生成新文件；PDF 或办公文档若面向不可信用户，应进入独立的扫描、隔离或异步处理流程。这些属于后续安全措施，不能被扩展名和 MIME 判断替代。

本地验收清单

接入后应至少准备以下六组样本，逐项确认成功或拒绝分支：

1. 小于 5 MiB 的真实 JPEG，扩展名为 .jpg，预期接受。
2. 真实 PNG 改名为 .jpg，预期因扩展名与 MIME 不匹配而拒绝。
3. 文本文件改名为 .pdf，预期拒绝。
4. 大于 5 MiB 的允许类型文件，预期在应用大小规则处拒绝。
5. 零字节文件，预期拒绝。
6. 允许类型但目标目录不可写，预期返回保存失败且不产生业务记录。

验收时还应查看磁盘：成功文件必须使用随机名称，失败样本不能出现在持久化目录中，同名原始文件连续上传也不应互相覆盖。若请求整体超过 post_max_size，$_FILES 可能不是预期结构，因此页面入口还可以结合请求大小与空数组情况给出更明确提示。

常见问题

为什么不能直接相信 $_FILES 中的 type？

该字段来自客户端提交，不能作为服务端接收依据。本文使用 Fileinfo 读取临时文件内容并返回 MIME，再与扩展名白名单成对比较。

只检查 MIME，不检查扩展名可以吗？

不建议。业务通常还需要稳定的后缀用于存储、下载响应或后续处理。扩展名和 MIME 分别来自名称与内容识别，成对匹配比单独列表更明确。

应用限制是 5 MiB，php.ini 应该也正好设为 5M 吗？

不应机械设成同一个值。post_max_size 包含整个请求体，除文件外还有 multipart 边界和其他字段，应给它留出余量；upload_max_filesize 也不能小于应用希望接收的最大文件。最终业务上限仍由代码明确执行。

Fileinfo 返回允许的 MIME 就代表文件安全吗？

不是。Fileinfo 根据文件内容特征识别类型，适合做类型约束，但不等于恶意内容扫描。面向不可信来源的文件还应结合隔离存储、权限控制、扫描流程与受控下载。