直接用 store() 方法最稳妥，它自动处理路径拼接、目录创建和唯一文件名生成；存 public disk 才能用 storage::url() 生成可访问 url，且需先运行 php artisan storage:link。
上传文件后存到 storage 的标准写法
直接用 store() 方法最稳妥，它自动处理路径拼接、目录创建和唯一文件名生成。别手动拼 storage_path() + 文件名，容易出错且不安全。
-
store()默认存到storage/app/下，传入子目录名即可分组，比如$request->file('avatar')->store('avatars')会存为storage/app/avatars/xxx.jpg - 如果要存到
storage/app/public/（方便用php artisan storage:link映射到 web 可访问路径），得显式指定 disk：$request->file('photo')->store('photos', 'public') - 不要用
move()或storeAs()手动控制文件名——除非你明确需要保留原始名，否则会引入重复覆盖或 XSS 风险（比如上传shell.php）
为什么不能直接用 Storage::put() 写原始文件流
Storage::put() 接收的是字符串或资源流，而 $request->file() 返回的是 UploadedFile 实例，二者类型不匹配。硬转会造成内容损坏或空文件。
- 错误写法：
Storage::put('test.jpg', $request->file('file'))—— 这实际是把对象转成字符串"Illuminate\Http\UploadedFile"存进去了 - 正确做法：先调
getRealPath()拿临时路径，再用file_get_contents()读取，但没必要，绕远路还占内存 - 真正该用
Storage::put()的场景是写程序生成的内容（如 PDF 字节流），不是处理上传文件
存完怎么拿到可访问的 URL
只有存到 public disk 的文件才能通过 Storage::url() 生成 URL；local disk（默认）不支持直接 URL 访问。
- 存的时候指定 disk：
$path = $request->file('doc')->store('docs', 'public') - 生成 URL：
Storage::url($path)→ 返回类似/storage/docs/abc.pdf - 前提：已运行
php artisan storage:link，且 web 服务器配置允许访问public/storage/目录 - 如果存的是
localdisk，只能用Storage::download()或自定义响应返回，不能给前端直链
常见报错和权限坑
最常遇到的是 Unable to write to directory 或 500 报错，基本都卡在权限或磁盘配置上。
- 检查
config/filesystems.php里disks.public.root是否指向storage_path('app/public')（默认是，别改错） - Laravel 9+ 默认
APP_URL是http://localhost，但Storage::url()生成的 URL 是相对路径，实际依赖 web 服务器能否解析/storage/别名 - Linux 上部署时，确保
storage/app和storage/app/public目录对 web 用户（如 www-data）有写权限，别只 chmod 755 了事，要用chmod -R 775 storage并 chown 正确用户 - 本地开发用 Valet / Homestead 一般没问题，但 Docker 环境里宿主机和容器的 uid/gid 不一致时，容易出现“看起来有权限却写失败”
disk 配置和权限问题不解决，代码写得再对也存不进去。真遇到存失败，先看日志里具体报哪一行、什么异常，别急着改逻辑。
