无法通过Postman将文件上传至Linux服务器/home目录问题排查

我正在开发一款向Linux服务器上传文件的移动应用，API基于同一服务器/var/www/html目录下的Laravel项目构建。为了将上传的图片存储到/home/uploads文件夹，我已在Laravel项目中设置FILESYSTEM_DRIVER=public和FILESYSTEM_PATH=/home/uploads。

控制器中的文件上传函数如下：

public function uploadFile(Request $request)
{
    if ($request->hasFile('file')) {
        Storage::putFileAs('Documents/', $request->file, 'Some name.jpg');
    }
}

本地直接运行Laravel代码时，文件能成功上传到/home/uploads/Documents/Some name.jpg，但通过Postman调用接口时，虽然返回成功消息，目标文件夹里却找不到文件。

Postman发送请求的截图：

1. 代码获取上传文件的方式错误 #

你代码里的$request->file是Laravel的内置方法，正确调用需要传入字段名，即$request->file('file')。本地测试可能因环境特殊能运行，但Postman传参时必须明确指定字段名才能正确获取文件。

修改后的代码：

public function uploadFile(Request $request)
{
    if ($request->hasFile('file')) {
        $file = $request->file('file');
        Storage::putFileAs('Documents/', $file, 'Some name.jpg');
    }
}

2. Web服务用户权限不足 #

本地运行代码用的是个人用户权限，而Postman调用接口时，服务器上的Web服务（如Nginx、Apache）是以www-data或nginx用户运行的，该用户可能没有/home/uploads文件夹的写入权限。

执行以下命令修复权限：

sudo chown -R www-data:www-data /home/uploads
sudo chmod -R 755 /home/uploads

3. Postman请求配置验证 #

• 确认请求方法为POST，Body选择form-data，字段类型设置为File（而非Text）；
• 检查请求头是否自动带上Content-Type: multipart/form-data，若未自动添加可手动补充。

4. Laravel文件系统配置检查 #

打开config/filesystems.php，确认public磁盘的配置是否正确读取环境变量：

'public' => [
    'driver' => 'local',
    'root' => env('FILESYSTEM_PATH', storage_path('app/public')),
    'visibility' => 'public',
],

同时检查.env文件里的FILESYSTEM_PATH=/home/uploads是否拼写正确，无多余空格。

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