PHP 文件上传后拿不到文件排查：从表单字段到 php.ini 限制

线上经常会遇到一个看似简单的问题：前端明明选择了文件，提交后 PHP 端却拿不到上传文件。有人第一反应是接口写错了，有人怀疑权限问题，但真正原因可能藏在表单编码、字段名、请求体大小、临时目录或上传错误码里。

这篇文章从一个实际排查现场出发，按“看到现象、提出猜测、动手验证、定位原因、修复方案、复查结果”的顺序，把 PHP 文件上传拿不到文件的问题拆开讲清楚。

问题现场：接口返回没有文件

我们先看现象。页面上有一个上传头像的表单，选择文件后点击提交，后端接口返回“未收到文件”。PHP 代码大概是这样：

如果只看这段代码，很容易以为是 avatar 字段没传。先不要急着改后端，我们要确认浏览器请求是否真的按文件上传格式发出。

初步判断：先看请求有没有按文件上传发送

PHP 接收文件上传有一个前提：表单必须使用 multipart/form-data。如果表单缺少这个编码方式，文件内容不会进入 $_FILES，后端自然拿不到。

  上传

接着打开浏览器开发者工具，查看 Network 面板里的请求头和请求体。请求头里应该能看到 multipart/form-data，请求体里应该有文件字段。如果请求还是普通表单编码，说明问题在前端表单或提交方式。

动手验证：检查字段名和错误码

如果请求格式正确，下一步看字段名。前端 name="avatar"，后端就要读 $_FILES['avatar']。字段名不一致时，文件其实到了 PHP，但你读错了数组下标。

这一步有两个作用：第一，确认实际字段名；第二，拿到上传错误码。常见错误码含义如下：

定位原因：php.ini 和临时目录也会拦住文件

现在可以定位到第二类常见原因：请求发来了，但 PHP 在进入业务代码前就把文件拦下了。这里重点看三个配置：

file_uploads = On
upload_max_filesize = 20M
post_max_size = 25M
upload_tmp_dir = /tmp

post_max_size 要大于单文件限制和其他表单字段总和；file_uploads 必须开启；临时目录必须存在且 Web 进程可写。如果错误码是 6，优先看临时目录；如果错误码是 1，优先看单文件限制。

修复方案：按链路逐项改正

修复时建议按链路顺序处理：

1. 表单使用 method="post" 和 enctype="multipart/form-data"。
2. 前端文件字段名和后端读取的 $_FILES 下标保持一致。
3. 确认 file_uploads 开启。
4. 确认 post_max_size 大于 upload_max_filesize。
5. 确认临时目录存在、可写、磁盘空间足够。
6. 保存前检查 error 是否为 0，再移动临时文件。

复查结果：用最小脚本确认上传成功

最后确认不要只看页面提示，应该用最小脚本复查三件事：$_FILES 中是否有正确字段、错误码是否为 0、目标目录是否真的出现文件。这样可以区分“接收失败”和“保存失败”。

 array_keys($_FILES),
    'avatar_error' => $_FILES['avatar']['error'] ?? null,
    'avatar_size' => $_FILES['avatar']['size'] ?? null,
], JSON_UNESCAPED_UNICODE);

总结清单

• $_FILES 为空，先检查表单编码和请求体。
• 字段名不一致，会导致后端读错位置。
• 有文件字段但上传失败，要看 error 错误码。
• 大文件失败时同时看 upload_max_filesize 和 post_max_size。
• 错误码指向临时目录时，检查目录是否存在、可写、磁盘是否足够。

总结一下，PHP 文件上传拿不到文件不是单点问题。只要按“表单编码、字段名、错误码、大小限制、临时目录、保存结果”这条链路查，基本都能快速定位。