Laravel Livewire文件上传提交返回Null问题排查求助

按优先级从高到低排查以下问题，基本可以覆盖所有该场景的报错：

• 表单缺少文件上传必需的enctype属性
  你当前的表单标签未声明enctype="multipart/form-data"，虽然高版本Livewire会尝试自动补全该属性，但在版本兼容、前端脚本干扰的场景下会失效，直接修改表单标签为：

  <form wire:submit.prevent="save" enctype="multipart/form-data">
  

  这是抄官方示例时最容易遗漏的细节，也是90%该类问题的诱因。
• 临时上传目录权限异常
  Livewire处理文件上传时会先将文件暂存到storage/app/livewire-tmp目录，目录不存在、web服务运行用户无读写权限时，上传会静默失败，字段值直接返回null。本地开发环境执行以下命令修复：

  # 首次使用文件上传功能先发布配置
  php artisan livewire:publish --config
  # 创建临时目录
  mkdir -p storage/app/livewire-tmp
  # 给storage目录授予可读写权限（生产环境请按服务器安全规范调整权限，不要直接用777）
  chmod -R 755 storage
  

• 异步上传未完成就触发提交
  Livewire的文件上传是前端异步执行的，选完文件立刻点提交时，如果临时文件还没上传完成，后端拿到的$photo就是null。可以在文件字段旁加上传状态提示，等上传完成再提交：

  <input type="file" wire:model="photo">
  <div wire:loading wire:target="photo">文件上传中，请稍候...</div>
  

  你之前在验证逻辑前写的dd($this->photo)如果是刚选完文件就点提交触发的，大概率是这个原因导致的。
• 基础配置校验
  确认以下几个写法没有错误：
  • WithFileUploads trait的命名空间引入正确，应为use Livewire\WithFileUploads;，不要引错其他同名类
  • 绑定的$photo属性必须声明为public，不能用protected/private修饰，Livewire无法访问非公共属性做双向绑定
  • 打开浏览器控制台排查JS报错，如果页面引入了其他修改file input行为的第三方脚本，暂时禁用后再测试是否正常

修正后的可运行代码参考：
组件代码：

<?php

namespace App\Http\Livewire;

use Livewire\Component;
use Livewire\WithFileUploads;

class UploadPhoto extends Component
{
    use WithFileUploads;

    public $photo;

    public function save()
    {
        $this->validate([
            'photo' => 'image|max:1024', // 单文件最大1MB
        ]);

        $this->photo->store('photos');
        $this->reset('photo'); // 上传完成后重置字段，避免重复提交
        session()->flash('message', '图片上传成功');
    }

    public function render()
    {
        return view('livewire.upload-photo');
    }
}

视图代码：

<form wire:submit.prevent="save" enctype="multipart/form-data">
    <input type="file" wire:model="photo">
    <div wire:loading wire:target="photo">文件上传中...</div>

    @error('photo') <span class="error">{{ $message }}</span> @enderror

    <button type="submit">保存图片</button>
</form>

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