Laravel API接收POST请求时无法获取上传文件问题咨询

最高发原因（覆盖90%同类问题） #

• 错误手动设置Content-Type: multipart/form-data请求头
  multipart/form-data请求必须携带自动生成的boundary分隔符，才能让服务端正确拆分普通参数和文件段。不管是Postman还是React请求库，只要手动硬编码这个请求头，就会丢失boundary参数，直接导致Laravel无法解析请求中的文件。

  修正方式：Postman中选择form-data传参时会自动生成合法请求头，不需要手动在Headers面板添加该字段；React侧使用axios/fetch提交FormData对象时，不要手动配置Content-Type，让浏览器自动生成带合法boundary的请求头即可。

• 错误使用$request->all()判断文件上传状态
  $request->all()仅返回普通文本类型的请求参数，不会包含上传的文件对象。哪怕文件上传完全正常，该方法的返回结果里文件字段也会显示为空。
  正确的调试打印代码如下：

  dd([
      'post_params' => $request->post(),
      'uploaded_files' => $request->allFiles(),
      'has_target_file' => $request->hasFile('你的文件字段名'),
      'upload_error_code' => $request->file('你的文件字段名')?->getError()
  ]);
  

剩余场景排查顺序 #

1. 校验请求头合法性
   临时在接口中打印$request->header('Content-Type')，确认返回值中包含boundary=----WebKitFormBoundaryxxx类的分隔符参数，如果没有说明请求侧头生成逻辑错误，回到请求端修正。
2. 检查PHP运行环境配置
   打开对应运行环境的php.ini文件，确认以下配置符合上传大小要求，修改后重启php-fpm或Web服务（Apache/Nginx）生效：

   file_uploads = On
   upload_max_filesize = 20M ; 按业务需求调整
   post_max_size = 25M ; 数值必须大于upload_max_filesize
   max_file_uploads = 20
   

3. 检查传参格式正确性
   • Postman侧：Body选择form-data类型后，文件字段右侧的类型下拉框必须选File，不能选Text，再选择本地文件上传，禁止将文件内容填入文本输入框。
   • React侧：必须使用原生FormData对象封装所有参数，禁止将File对象塞进JSON结构提交，参考写法：

     const formData = new FormData();
     formData.append('cover', fileInstance); // fileInstance为input组件获取到的File对象
     formData.append('other_param', '参数值'); // 其他普通参数同样append到formData
     axios.post('/api/your-upload-path', formData); // 不手动设置Content-Type
     

4. 检查中间件与代理配置
   • 确认接口所在路由组没有自定义中间件篡改请求体，尤其是全局处理JSON请求的中间件不要覆盖multipart类型请求的解析逻辑。
   • 如果服务前部署了Nginx反向代理，确认Nginx配置中client_max_body_size参数值大于上传文件大小，否则请求会被Nginx提前拦截，Laravel无法接收到完整请求内容。

内容的提问来源于stack exchange，提问作者ManiMuthuPandi