上传图片前必须配置 disk，否则 storage::put() 报错；应使用 public disk 并运行 storage:link，确保目录存在、权限正确、web 服务器路由配置匹配，且用 request()->file() 获取文件并校验有效性。
上传图片前必须配置 disk，否则 Storage::put() 直接报错
很多人一上来就写 Storage::put('avatars', $file)，结果抛出 League\Flysystem\FilesystemException 或 “Unable to write file” —— 根本原因不是代码写错，而是 config/filesystems.php 里默认的 'default' disk 没配好。
常见错误场景：本地开发用 local，但没确认 root 路径是否存在或有写权限；线上用 s3 却漏了 AWS_ACCESS_KEY_ID 环境变量。
-
localdisk 必须确保'root' => public_path('storage')对应目录真实存在且 web server 可写（比如 Nginx 用户要能写入） - 若想把图片存到
public/下便于直接访问，别用storagedisk，改用publicdisk，并在config/filesystems.php中确认它指向public_path() - 运行
php artisan storage:link只是为storage/app/public创建软链，对publicdisk 无效，别混淆
request()->file() 和 $request->file() 都行，但别用 $request->input()
图片是二进制文件流，不是普通表单字段。用 $request->input('avatar') 拿到的只是字符串 "tmp_name" 的路径名（而且还是空的），根本不是文件对象。
正确入口只有两个：request()->file('avatar') 或 $request->file('avatar')，返回的是 Illuminate\Http\UploadedFile 实例。
- 务必先调用
->isValid()判断上传是否成功，比如用户取消上传、超大小、PHP 配置限制等都会导致无效 -
->getClientOriginalName()是原始文件名，含扩展名；->extension()更安全，只取扩展名（防伪造） - 别直接拼接用户传来的文件名存盘，否则可能被构造为
../../../.env—— 用Str::random(16) . '.' . $file->extension()生成新名
用 Storage::putFile() 比 put() 更省心，但要注意自动命名规则
Storage::putFile('avatars', $file) 会自动生成唯一文件名并保存，而 Storage::put('avatars/'.$name, $file) 要自己处理路径和冲突。多数情况推荐前者。
PHP中文网提供Laravel 13.2.0版本下载，Laravel框架 是基于 PHP 8.3+ 的高性能框架，官方推荐通过 Composer 安装。它内置 AI SDK、JSON:API Resources 及原生向量搜索，支持属性驱动开发与队列路由，大幅提升开发效率。相比旧版，13.2.0 优化了缓存 TTL 管理与实时通信，无需 Redis 即可横向扩展。作为现代 Web 开发首选，它兼顾安全与极速体验，助您快速构建企业级应用。
但它的默认行为是：把文件存到 avatars/随机哈希.扩展名，且返回完整路径（如 avatars/abc123.jpg）。如果你需要保留原名，得加第二个参数：
Storage::putFile('avatars', $file, 'public')
注意第三个参数是 visibility，不是文件名 —— 想控制名字，得用 putFileAs()：
Storage::putFileAs('avatars', $file, 'user_'.Auth::id().'.'.$file->extension(), 'public')
-
putFile()默认用'private'可见性，存到localdisk 时不影响，但存到s3就会导致 URL 403 - 如果 disk 是
public，visibility 设为'public'才能通过Storage::url()生成可访问链接 -
putFile()内部会自动调用moveTo()，所以不用手动$file->store()或->move()
Storage::url() 返回的链接不生效？检查 disk 类型和 soft link
调用 Storage::url('avatars/abc.jpg') 返回 /storage/avatars/abc.jpg，但浏览器打开 404 —— 这不是代码问题，是部署问题。
只有两种 disk 支持 url()：类型为 local 且配置了 'url' 键（比如 public disk），或 s3 类型 disk。而默认的 storage disk（local 类型但 root 在 storage/app）不支持 url()，强行调用会抛异常。
- 确认你在用
publicdisk：配置中'disks.public.root' => public_path('storage')，且已运行php artisan storage:link -
storage:link创建的是public/storage → storage/app/public，所以文件必须存到publicdisk 的public/子目录下才有效 - Apache 需开启
mod_rewrite，Nginx 要配好location /storage { alias ... }，否则静态路由不通
真正容易被忽略的是：disk 配置、软链路径、Web 服务器路由三者必须严格对应，差一个环节，url() 就是死链。
