Laravel文件上传失败主因是Storage路径配置或权限问题：需确认磁盘驱动与物理路径匹配、public/storage软链接有效、Web服务器用户对storage目录有读写权限、store()方法显式指定'public'磁盘，并开启APP_DEBUG=true捕获具体错误日志。
Laravel 文件上传失败，很多时候不是代码写错了，而是 Storage 路径配置或权限没对。直接看日志可能只报“Unable to write”或“File not found”，但真正卡点往往在存储驱动、符号链接、目录权限或 .env 配置上。下面几步能快速定位问题。
确认当前 Storage 驱动和实际路径
运行以下命令查看 Laravel 当前使用的默认文件系统磁盘及其配置：
-
php artisan tinker 进入交互环境，执行：
Storage::disk('public')->getDriver()->getAdapter()->getPathPrefix()
这会输出类似/var/www/html/storage/app/public/的真实物理路径。 - 检查
config/filesystems.php中'public'（或你用的其他磁盘）是否指向正确路径，尤其注意'root'和'url'是否匹配。 - 如果用了
local驱动但想通过 URL 访问，必须确保public/storage是指向storage/app/public的有效软链接 —— 运行php artisan storage:link创建或重建它。
检查目录权限和所有权
Linux 环境下，Web 服务器用户（如 www-data 或 nginx）必须对目标目录有读写权限：
- 运行
ls -la storage/app/和ls -la public/storage，确认所属用户组与 Web 服务一致。 - 常见修复命令：
sudo chown -R www-data:www-data storage/ bootstrap/cache/sudo chmod -R 775 storage/ bootstrap/cache/ - 若用 Docker，还要确认容器内用户 UID 匹配宿主机，或在 docker-compose.yml 中指定
user: "www-data"。
验证上传逻辑是否命中正确磁盘
别只看 store() 方法，要确认它用的是哪个磁盘：
- 默认
$request->file('xxx')->store('uploads')使用config('filesystems.default')对应的磁盘（通常是local），而非public。 - 显式指定磁盘更安全：
$request->file('avatar')->store('avatars', 'public')—— 这样才真正存到storage/app/public/并可通过/storage/xxxURL 访问。 - 上传后用
Storage::disk('public')->exists('avatars/filename.jpg')手动验证文件是否存在。
打开日志并捕获具体错误
别依赖浏览器静默失败，让错误浮出水面：
- 确保
.env中APP_DEBUG=true，且LOG_LEVEL=debug。 - 上传时故意传一个超大文件或不支持类型，观察
storage/logs/laravel.log最末几行，常有类似：Failed to write file "/var/www/html/storage/app/public/xxx.jpg": mkdir(): Permission denied - 也可临时加日志：
Log::info('Upload path:', ['path' => Storage::disk('public')->path('')]);
