Laravel API端点上传文件提示File参数必填错误如何解决

核心错误点 #

• 错误1：Guzzle的multipart参数结构错误，不应该在file字段内手动添加Content-type声明，Guzzle发送multipart请求时会自动生成正确的请求头和边界标识，多余的声明会破坏请求结构，导致后端无法正常解析文件字段。
• 错误2：文件路径错误导致fopen读取失败，返回空值。你当前使用相对路径storage.$value读取文件，在队列Job的CLI运行环境下，工作目录不是项目根目录，会找不到对应文件；且你上传文件时用的是Laravel的public磁盘，存储根目录为storage/app/public，当前拼接的路径缺省了app/public部分，也会导致文件读取失败。
• 错误3：缺少文件存在性校验，即使文件读取失败也直接发送请求，自然会出现File parameter is required报错。
• 额外问题：控制器中如果用户未上传logo，$logo变量会保留初始的$request['logo']值（大概率为null），此时Job调用上传接口会直接传空路径，也会触发报错。

修复步骤 #

1. 先修改groupImage方法，修正参数结构和路径问题：

public function groupImage(string $groupId, string $value)
{
    // 生成绝对路径，确保CLI环境下也能正确读取文件
    $filePath = storage_path('app/public' . $value);
    // 先校验文件是否存在
    if (!file_exists($filePath)) {
        throw new \Exception("文件不存在：".$filePath);
    }
    return $this->doRequest2('POST', "group-pic", [
        'multipart' => [
            [
                'name' => 'phone',
                'contents' => $groupId,
            ],
            [
                'name' => 'file',
                'contents' => fopen($filePath, 'r'),
                // 可选：补充文件名字段，部分接口会校验文件名后缀
                'filename' => basename($value)
            ]
        ]
    ]);
}

2. 再修改Job的调用逻辑，只有存在logo时才发起上传请求：

// 设置私有群组
if ($this->private == '1'){
    $grupoPrivado = $ZApi->setGroupMessages($idGroup, 'true');
    $adminOnly =  $ZApi->setGroupEdit($idGroup, 'true');
}
// 新增非空判断
if ($this->logo) {
    $setImg =  $ZApi->groupImage($idGroup, $this->logo);
}

可选校验步骤 #

如果修改后还是报错，可以在发送请求前打印请求结构校验参数，和Postman发送的请求结构做对比，确保字段名、内容完全一致。

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