hyperf验证图片格式失败的典型原因是php缺少fileinfo扩展，导致validation组件无法通过finfo_file()判断真实mime类型；需检查并确保cli与fpm环境均启用extension=fileinfo，linux下可通过apt安装对应版本扩展并重启服务。
Hyperf验证图片格式失败的典型表现
当你在Hyperf中用 image 或 mimes:jpeg,jpg,png,gif 规则验证上传文件时，明明传的是正常 JPG，却报错 The uploaded file is not a valid image. —— 这大概率不是规则写错了，而是 PHP 缺少 fileinfo 扩展。Hyperf 的 Validation 组件（基于 illuminate/validation）依赖 finfo_file() 判断真实 MIME 类型，没这个扩展就只能靠文件后缀猜，而猜的结果被默认拒绝。
确认是否缺失 fileinfo 扩展
运行以下命令检查：
php -m | grep fileinfo
如果无输出，说明未启用；若输出 fileinfo，但验证仍失败，请继续检查 CLI 和 FPM 使用的 PHP 配置是否一致（常见于 Docker 或多版本共存环境）：
-
php --ini查看 CLI 加载的php.ini -
php-fpm -i | grep "Loaded Configuration File"查看 FPM 加载的配置 - 确保两个环境都启用了
extension=fileinfo行（注意不是注释状态）
Linux 下安装 fileinfo 扩展（以 Ubuntu/Debian 为例）
多数现代 PHP 包已内置 fileinfo，但常被默认禁用。先确认 PHP 版本：
php -v
然后执行对应操作：
- PHP 7.4：
sudo apt install php7.4-fileinfo - PHP 8.0：
sudo apt install php8.0-fileinfo - PHP 8.1+：
sudo apt install php-fileinfo（通常已随主包安装） - 装完后重启服务：
sudo systemctl restart php*-fpm或sudo service php*-fpm restart
注意：Docker 用户需在 Dockerfile 中显式安装，例如 RUN docker-php-ext-install fileinfo（适用于官方 php:alpine 或 php:apache 镜像）。
验证修复是否生效
写个最小测试脚本确认 finfo_file() 可用：
<?php $finfo = finfo_open(FILEINFO_MIME_TYPE); var_dump(finfo_file($finfo, $_SERVER['SCRIPT_FILENAME'])); finfo_close($finfo); ?>
若输出类似 string(24) "text/x-php"，说明扩展工作正常。再回到 Hyperf 接口测试上传，此时 image 规则应能正确识别 JPG/PNG 等真实图片类型。特别注意：某些 PNG 文件若带非标准 chunk（如 Photoshop 保存的），仍可能被拒绝——这不是扩展问题，而是 libmagic 数据库限制，可临时改用 mimetypes:image/jpeg,image/png 替代 mimes 规则绕过深度检测。
最容易被忽略的是 CLI 和 Web SAPI 使用不同 php.ini —— 验证时用 php -m 看到有 fileinfo，不代表 FPM 进程真加载了它。
