Symfony中处理文件上传需分场景：手动提取UploadedFile适用于AJAX等定制场景，须校验类型、错误码、安全命名并递归创建ID分层路径；表单绑定则依赖isValid()后取值并move；统一存储推荐Flysystem，注意配置绝对路径与响应类型。
在 Symfony 应用中处理用户上传的图片、文档等文件时，必须确保接收可靠、验证充分、存储安全且路径可扩展，否则单目录堆积数千文件会导致系统遍历变慢、备份失败、CDN 缓存失效甚至 ext4 文件系统单目录 32K 限制被突破。
手动提取并保存 UploadedFile 对象
适用于 AJAX 上传、自定义表单或需要精细控制流程的场景，不依赖表单组件绑定。
第一步：从 Request 对象中获取上传文件实例，字段名必须与前端 name="image" 完全一致。
第二步：检查对象类型是否为 UploadedFile，若为 null 或非实例，说明前端未发送该字段或名称拼写错误。
第三步：调用 $file->getError() === UPLOAD_ERR_OK 确认上传无客户端中断、超限等错误；【跳过此检查将导致静默失败，后续 move() 报错但无明确提示】
第四步：构建目标路径——使用实体 ID 创建子目录，例如 sprintf('%s/private/%d', $projectDir, $post->getId())；【必须用 mkdir(..., 0755, true) 启用递归创建，否则路径不存在时 move() 直接抛出异常】
第五步：生成安全文件名，过滤原始名称中的路径遍历字符（如 ../）和非法符号，再拼接唯一后缀与扩展名，最后执行 $file->move($targetDir, $fileName)。
通过表单组件自动绑定上传
适合标准 HTML 表单提交，由 Symfony 自动解析 $_FILES 并注入验证逻辑。
方法一：在表单类型类中添加 FileType 字段，并配置 required 和 mimeTypes 约束。
方法二：控制器中调用 $form->handleRequest($request)，框架自动完成临时文件实例化。
方法三：仅当 $form->isValid() 返回 true 后，才从表单数据中取出 $file = $data['image']；【若跳过 isValid() 检查直接取值，可能拿到 null 或未验证的非法文件】
方法四：调用 $file->move($uploadDir, $safeName) 完成落盘，注意不可保存 $file->getRealPath() 到数据库——该路径指向临时目录，请求结束后即失效。
使用 Flysystem 统一管理存储
当项目需支持本地磁盘、S3、FTP 等多种后端，或要求读写接口一致时，Flysystem 是必选项。
确认已安装官方推荐的 league/flysystem-bundle，而非已废弃的 OneupFlysystemBundle；混用会导致服务无法注入。
配置 config/packages/flysystem.yaml 中的 directory 必须为绝对路径，例如 '%kernel.project_dir%/public/uploads'；写成 data/ 将实际指向 PHP 当前工作目录（通常是 public/），不是项目根。
在控制器中通过类型提示自动注入 FilesystemOperator $defaultStorage，然后调用 $defaultStorage->write('images/photo.jpg', $contents) 即可完成写入。
下载响应不能直接返回 $defaultStorage->read() 的结果——它返回字符串，而 Symfony 响应需是 BinaryFileResponse 或流式输出；应改用 new StreamedResponse(...) 包装 fopen($defaultStorage->readStream(...), 'rb')。
