使用GuzzleHttp转发multipart/form-data文件出现Unexpected field错误如何解决？

错误原因及解决方案 #

• Guzzle的multipart参数赋值错误
  PHP的$_FILES['images']是存储上传文件元信息的数组，包含临时文件路径、原始文件名、错误码等属性，不能直接作为文件内容传递给Guzzle。需要读取临时文件的资源流作为contents参数值。
• 目标接口字段名不匹配
  Unexpected field错误的核心诱因是你提交的表单字段名和目标接口预期的接收字段不一致。当前代码配置的文件字段名是images，请确认目标接口要求的字段名是否为其他值（比如file、upload、image等）。
• 缺少前端上传结果校验
  如果前端上传文件失败（比如文件超限、网络中断），$_FILES['images']内容为空或携带错误信息，直接转发也会触发该报错。

修正后的后端代码 #

<?php
// 先校验文件是否上传成功
if (!isset($_FILES['images']) || $_FILES['images']['error'] !== UPLOAD_ERR_OK) {
    // 自定义上传错误处理逻辑
    die('文件上传失败');
}

$client = new GuzzleHttp\Client(['base_uri' => 'http://example.com/']);
$res = $client->request('POST', 'another-endpoint/', [
    'multipart' => [
        [
            'name'     => 'images', // 请替换为目标接口要求的文件字段名
            'contents' => fopen($_FILES['images']['tmp_name'], 'r'),
            'filename' => $_FILES['images']['name'] // 可保留原始文件名或自定义
        ],
    ],
]);

额外排查建议 #

如果修改后仍然报错，可以先通过Postman直接调用目标接口，确认正确的请求参数格式后再对齐后端配置。

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