symfony 6.3 文件上传验证失败主因是配置或环境问题：表单缺 enctype="multipart/form-data"、字段名不匹配、filetype 未映射、required 未显式设置、错误未正确渲染或 php/服务器上传限制触发。
Symfony 6.3 文件上传表单验证失败，多数情况不是代码逻辑出错，而是配置、环境或校验链路某处被跳过。重点排查方向是：表单是否真正提交了文件、验证约束是否生效、错误是否被正确渲染。
确认文件已实际提交到后端
很多“验证失败”其实是文件根本没传过来：
- HTML 表单必须带 enctype="multipart/form-data"，缺了这行，
$request->files恒为空，后续所有验证都不会触发 - 检查表单字段名（如
name="document"）是否与控制器中$form->get('document')或$request->files->get('document')的键完全一致（大小写敏感） - 使用 FileType 字段时，确保它没被设为
'mapped' => false，否则表单不会绑定 UploadedFile 实例 - 在控制器里加一行调试：
dump($request->files->get('document'));，看返回的是UploadedFile实例还是null
验证约束是否真正运行
FileType 字段的验证容易“静默失效”：
-
required 必须显式设置：即使写了
Constraints\File，若没配'required' => true（或没删掉默认true），空提交时整个字段会被跳过，验证器根本不执行 - 约束要放在表单类型类里，不是实体类上——实体接收的是路径或名称，不是 UploadedFile 对象
- 用
dump($form->getErrors(true))查看是否有验证错误；若为空，大概率是字段没提交或 required 配置导致跳过验证 - 避免只依赖前端 required 属性，它可被绕过；服务端
NotBlank+File约束必须同时存在
错误信息是否能被模板显示
验证失败了，但页面没报错？这是最常见误解：
-
{{ form_errors(form) }}默认不显示字段级错误，只显示表单级全局错误（如 CSRF 失败）。FileType 的 NotBlank 错误属于字段级，需单独写{{ form_errors(form.document) }} - 或者在字段定义中加
'error_bubbling' => true，让错误上浮到表单根节点，此时{{ form_errors(form) }}才能捕获 - 不要在 Twig 中只用
{{ form_widget() }}，它不自动渲染错误；务必配合{{ form_errors() }}使用 - 检查浏览器开发者工具 Network 标签页，确认响应状态码是 200（而非 302 重定向掩盖了错误）
排除 PHP 和服务器层硬性拦截
上传中途断掉，常被误判为验证失败：
- 检查
php.ini：确保upload_max_filesize和post_max_size足够大（比如都设为20M），改完记得重启 PHP-FPM 或 Apache - Nginx 用户额外确认
client_max_body_size，默认常为 1M，小文件正常、大文件直接 413 Request Entity Too Large - 临时在控制器开头加校验：
if (!$uploadedFile || !$uploadedFile->isValid()) { throw new \RuntimeException('Upload error: ' . $uploadedFile->getError()); }，可快速暴露底层错误码（如UPLOAD_ERR_INI_SIZE）
