PHP finfo_file 按文件内容识别 MIME 类型的实现方法

处理上传文件或未知后缀的本地文件时，PHP 不应该只看文件名。finfo_file() 会根据文件内容调用 Fileinfo 的 magic database，返回类似 image/png 的 MIME 类型。实用写法是先用 FILEINFO_MIME_TYPE 创建 finfo 对象，再检查文件是否可读、返回值是否为 false，最后把结果交给业务白名单判断。

官方参考：https://www.php.net/manual/en/function.finfo-file.php

最小可靠链路是“路径可读 → finfo_file 识别 → 处理 false/ValueError → 比较允许的 MIME 集合”。扩展名只能作为展示或初筛信息，不能替代内容识别；而 MIME 识别本身也不等于完整的文件安全审查。

先记住三点：使用 FILEINFO_MIME_TYPE 可以得到不带字符集的 MIME 值；读不到文件时优先修复路径或权限，不要把 false 当成字符串；如果输入路径可能来自外部，先拒绝空字节并限定可访问目录。

finfo_file 识别的到底是什么

finfo_file() 的输入是一个已存在的文件路径，返回文件内容的文字描述，或者在发生错误时返回 false。当对象用 FILEINFO_MIME_TYPE 初始化时，结果通常是纯 MIME 类型，例如 text/plain、image/png 或 application/pdf。这和 pathinfo($path, PATHINFO_EXTENSION) 不同：后者只看文件名。

用 FILEINFO_MIME_TYPE 读取并处理结果

下面的代码把识别过程压缩成一个可复用的边界函数。它先检查普通文件和可读性，再拒绝空字节路径；finfo::file() 成功后才进入允许集合。示例中的集合只是业务示意，实际项目应按接口用途维护，而不是把所有返回值都放行。

file($path);
    } catch (ValueError $e) {
        // PHP 8.5 对含空字节的文件名抛出 ValueError，保留为参数错误。
        throw new InvalidArgumentException('文件路径参数无效', 0, $e);
    }

    // file() 失败时返回 false，不能直接传给字符串比较或数组键查询。
    if ($mime === false) {
        throw new RuntimeException('Fileinfo 无法识别文件内容');
    }

    return $mime;
}

// 允许集合应由当前业务定义，而不是由文件扩展名推导。
$allowedMime = ['image/png', 'image/jpeg', 'application/pdf'];
$mime = detectMimeForAllowList($path);

if (!in_array($mime, $allowedMime, true)) {
    throw new RuntimeException('文件类型不在允许范围内');
}
// 通过白名单后，才进入保存、解析或转码等后续流程。

返回 false、字符集和异常怎么区分

排查时不要只打印一个“类型不对”。先把情况拆开：路径不存在或权限不足属于输入环境问题；file() 返回 false 表示 Fileinfo 这次没有得到结果；识别出的字符串则是一个可供业务判断的值。若使用的是 PHP 8.5，传入含空字节的文件名会抛出 ValueError；更早版本的异常类型不同，因此边界校验放在调用前更稳定。

只把 MIME 识别当作链路中的一环

文件内容识别比扩展名可靠，但它回答的是“看起来是什么类型”，不是“这个文件能否安全处理”。上传场景还应限制文件大小和保存位置，使用随机服务端文件名，按业务决定是否重新编码或交给专用解析器，并在允许集合之外拒绝继续处理。也不要把用户声明的 Content-Type 当成检测结果。

如果同一文件在不同机器上得到不同结果，优先检查 PHP 是否启用了 Fileinfo、magic database 是否可用，以及部署环境的文件内容是否完整。不要先把扩展名改成另一个后缀来“修复”识别结果。

相关问题

finfo_file 和 mime_content_type 应该选哪个？

新代码优先使用 finfo 对象和 FILEINFO_MIME_TYPE，因为调用意图、返回值和异常边界更明确。若项目已有 mime_content_type()，也应核对 Fileinfo 扩展是否可用，并统一后续白名单逻辑。

识别出 image/png 就能保证文件安全吗？

不能。它只说明内容特征匹配 PNG 的 MIME 判断，不能替代大小限制、解析器防护、存储隔离和必要的重新编码。真正放行前仍要按文件用途补齐这些控制。