Upload类校验失败抛出的是think\exception\_ValidateException（带下划线），非标准ValidateException或InvalidArgumentException，必须用完整命名空间捕获。
Upload类抛出的_ValidateException不是标准异常类型
ThinkPHP 的 Upload 类（尤其 5.1/6.0 中的 think\File 或 think\facade\Filesystem 配合验证时）在文件校验失败时，会抛出 _ValidateException —— 它**不是 think\Exception\ValidateException，也不是 PHP 原生 InvalidArgumentException**，而是一个内部定义、未公开暴露的类，位于 think\exception\_ValidateException（注意开头的下划线）。直接 catch (ValidateException $e) 会捕获不到。
- 它继承自
think\Exception，但类名带下划线，IDE 不提示，文档几乎不提 - 常见触发场景：
size、ext、image等验证规则不通过时，且你用了validate()方法或配置了rule - 如果没显式 catch，它最终会被全局异常处理接管，但此时已丢失上传上下文（比如哪个字段、原始文件名）
必须用完整命名空间捕获 _ValidateException
唯一可靠方式是写全路径：用 think\exception\_ValidateException。别省略 think\exception\，也别去掉开头的下划线——少一个字符都 catch 不住。
- 正确写法：
catch (\think\exception\_ValidateException $e)（注意开头的反斜杠） - 错误写法：
catch (_ValidateException $e)、catch (ValidateException $e)、catch (\_ValidateException $e) - 建议和
think\exception\FileException、think\exception\ValidateException一起捕获，覆盖更全：try { $file->validate(['size' => 2097152, 'ext' => 'jpg,png'])->move($path); } catch (\think\exception\_ValidateException $e) { // 这里才能真正拿到上传验证失败 $msg = $e->getMessage(); // 如 "上传文件大小不得超过2M" } catch (\think\exception\FileException $e) { // 文件移动失败等系统级错误 }
统一接管的关键是「提前拦截」而非「兜底处理」
很多人想在 app/exception/Handle.php 里统一处理所有上传异常，但 _ValidateException 在默认异常处理流程中**不会进入 render() 方法的标准分支**——它被中间件或验证器提前吞掉了，或者因命名特殊被忽略。
- 最稳做法：在控制器里对每个
$request->file()调用做独立 try/catch，别依赖全局 - 如果真要统一，需在公共基类或 Service 层封装上传逻辑，并强制 throw 新异常（如
UploadValidateException），再由全局 Handle 捕获这个新类型 - 别试图用
set_exception_handler()拦截——它收不到框架内抛出的该异常，PHP 层面已被捕获过一次 - 注意：TP6 中若使用
think\facade\Filesystem+upload驱动，验证异常可能走的是think\exception\ValidateException，和Upload类行为不一致，务必按实际类名调试
容易漏掉的两个上下文信息
即使捕获成功，_ValidateException 对象本身不携带原始文件名、表单字段名、临时路径这些关键信息。它只负责报错，不负责“交代背景”。
立即学习“PHP免费学习笔记（深入）”；
- 必须在 catch 前手动记录：
$file->getInfo()['name']、$file->getRule()、$file->getError()（这个有时比异常 message 更准） - 别依赖
$e->getFile()—— 它返回的是异常类文件路径，不是上传文件路径 - 示例补全：
if ($file && $file->isValid()) { $originalName = $file->getInfo()['name']; try { $file->validate(['ext' => 'pdf'])->move($path); } catch (\think\exception\_ValidateException $e) { throw new \think\exception\HttpException(400, "文件 {$originalName} 验证失败：{$e->getMessage()}" ); } }
