TP6.0接收FormData文件为空的根源在于PHP multipart解析配置未启用或不合理，以及前端请求头、name匹配、多文件写法等与TP6机制不兼容；需确保php.ini中file_uploads=On、upload_max_filesize和post_max_size设置合理并重启服务，前端禁用手动Content-Type，name严格匹配，多文件须逐个append同名键，同时注意中文文件名RFC 2231编码问题。
TP6.0 接收前端 FormData 提交的文件时，常出现 file 参数为 null、$_FILES 为空、上传成功但后端读不到文件内容 等问题，根源多在 multipart 解析环节未适配 TP6 的底层机制与 PHP 运行环境限制，而非单纯前端传错。
确认 PHP 配置是否允许 multipart 解析
打开 php.ini，检查以下三项必须启用且值合理：
file_uploads = On
upload_max_filesize = 20M
post_max_size = 25M（必须 ≥ upload_max_filesize + 所有其他字段总大小）
【post_max_size 小于实际请求体大小会导致整个 $_POST 和 $_FILES 清空，TP6 拿不到任何 multipart 数据】
立即学习“前端免费学习笔记（深入）”；
改完需重启 PHP-FPM 或 Apache，用 phpinfo() 页面验证生效状态。
TP6 中正确获取 FormData 文件对象
前端用 new FormData() 构建数据并调用 axios 或 fetch 上传时，绝不可手动设置 Content-Type 请求头。
方法一：使用 TP6 内置 request->file()
在控制器中直接写：$file = $this->request->file('avatar'); —— 其中 'avatar' 必须与 FormData.append('avatar', file) 的第一个参数完全一致，区分大小写。
方法二：从 $_FILES 全局变量取（仅限调试或兼容旧逻辑）
TP6 默认会将 $_FILES 映射到 Request 对象，但若中间件或自定义 input 处理覆盖了原始 $_FILES，就可能丢失。此时可绕过框架直接读：$rawFile = $_FILES['avatar'] ?? null;，再用 tp 的 think\File 类封装：new \think\File($rawFile);
FormData 多文件上传的写法陷阱
前端若想一次传多个同名文件（如 avatar[]），常见错误是：
❌ 错误写法：formData.append('avatar', [file1, file2]); → 后端收到的是字符串 "[object File],[object File]"，不是文件数组。
✅ 正确写法：对每个文件单独 append，name 相同即可：
for (let i = 0; i formData.append('avatar', files[i]);
}
TP6 会自动将同名多个 file 合并为数组，$this->request->file('avatar') 返回 File 对象数组，可遍历处理。
TP6 解析 multipart 时的编码与中文文件名问题
第一步：确保 Nginx/Apache 未强制修改请求头
某些反向代理配置会 strip boundary 或重写 Content-Type，导致 TP6 无法识别 multipart 格式。检查 access_log 中上传请求的原始请求头，确认 Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryxxx 完整存在。
第二步：TP6 默认不处理 RFC 2231 编码的中文 filename
当浏览器上传含中文名的文件（如“测试文档.pdf”），部分 Chromium 内核会生成 filename*=utf-8''%E6%B5%8B%E8%AF%95.pdf 形式，而 TP6 的 \think\File->__construct() 仅解析传统 filename="测试文档.pdf"，对 RFC 2231 编码字段直接忽略，导致 $file->getOriginalName() 返回空字符串。
解决方法：在获取文件后手动解码：
$file = $this->request->file('doc');
if ($file && method_exists($file, 'getInfo')) {
$rawName = $file->getInfo('name');
if (strpos($rawName, "utf-8''") === 0) {
$decoded = rawurldecode(substr($rawName, 7));
$file->setOriginalName($decoded);
}
}
TP6 中禁用 multipart 自动解析的场景与操作
某些接口需同时接收 JSON body 和文件（如混合表单），前端用 multipart 发送，但 TP6 默认只解析文件和普通字段，不解析嵌套 JSON 字符串字段。
此时不能依赖 $this->request->param() 获取 JSON 字段，因为 multipart 解析器会把 JSON 当作纯文本字段，不做 json_decode。
正确做法：先用 $this->request->param('metadata') 获取原始字符串，再手动 json_decode：
$metaStr = $this->request->param('metadata');
$metadata = is_string($metaStr) ? json_decode($metaStr, true) : null;
【切勿在 multipart 请求中对同一接口既开 JSON 中间件又开文件上传，会导致解析冲突】
