Laravel图片上传教程使用Storage类实现文件存储

在 Laravel 项目中处理图片上传功能时，开发者常会遇到一些配置与代码层面的典型问题。本文将系统梳理几个关键环节的解决方案，帮助您优化流程，避免常见错误。

上传前务必正确配置存储磁盘（Disk），否则 Storage::put() 将报错

许多开发者在编写上传代码时，直接调用 Storage::put('avatars', $file)，随即遭遇 League\Flysystem\FilesystemException 或“Unable to write file”错误。这通常并非逻辑错误，而是配置文件中的默认磁盘（'default' disk）未正确设置所致。

例如，在本地开发环境中使用 local 磁盘时，需确保 root 配置指向的目录真实存在，且 Web 服务器运行用户（如 www-data）拥有写入权限。在线上环境配置 s3 等云存储时，则必须检查 AWS_ACCESS_KEY_ID 等关键环境变量是否已设置。

• 使用 local 磁盘时，请确认 'root' => public_path('storage') 对应的目录已创建，并确保 Nginx 或 Apache 用户具备写入权限。
• 若希望上传的图片能通过 URL 直接访问，建议存储至 public/ 目录。此时应使用 public 磁盘而非默认的 storage 磁盘，并在 config/filesystems.php 中确认其指向 public_path()。
• 额外提示：运行 php artisan storage:link 命令是为 storage/app/public 创建符号链接至 public/storage，这与 public 磁盘的配置是两回事，请勿混淆。

正确获取上传文件：使用 request()->file() 或 $request->file()，避免 $request->input()

图片文件属于二进制数据流，并非普通的表单文本字段。若使用 $request->input('avatar') 获取，得到的将是一个字符串（可能为空），而非可操作的文件对象。

正确的获取方式有两种：request()->file('avatar') 或 $request->file('avatar')。两者均返回一个 Illuminate\Http\UploadedFile 实例。

• 获取文件实例后，首要步骤是调用 ->isValid() 方法，验证上传是否成功。用户取消、文件大小超限、PHP 配置限制等均可能导致上传无效。
• ->getClientOriginalName() 可获取原始文件名（含扩展名），而 ->extension() 则更安全，它仅提取扩展名部分，能有效防止文件名伪造攻击。
• 重要安全提示：切勿直接将用户上传的文件名拼接路径存储，这存在安全风险（如构造 ../../../.env 进行路径遍历）。推荐使用 Str::random(16) . '.' . $file->extension() 等方式生成随机唯一文件名。

优先使用 Storage::putFile() 简化操作，但需留意其自动命名规则

Storage::putFile('avatars', $file) 是一个便捷方法，它会自动生成唯一文件名并完成保存。相比之下，Storage::put('avatars/'.$name, $file) 则需要开发者自行处理完整路径与潜在的文件名冲突。多数场景下，推荐使用前者。

然而，putFile() 的默认行为是将文件保存为类似 avatars/随机哈希.扩展名 的格式，并返回完整路径（如 avatars/abc123.jpg）。若需保留原始文件名，则需传递额外参数。

Storage::putFile('avatars', $file, 'public')

请注意，此处第三个参数是文件的可见性（visibility），而非文件名。如需精确控制存储后的文件名，应使用其关联方法 putFileAs()：

Storage::putFileAs('avatars', $file, 'user_'.Auth::id().'.'.$file->extension(), 'public')

• putFile() 默认使用 'private' 可见性。当使用 local 磁盘时影响不大，但若使用 s3 等云存储，文件链接可能返回 403 错误。
• 若磁盘配置为 public，请务必将 visibility 设置为 'public'，如此通过 Storage::url() 生成的链接方可被公开访问。
• 另外，putFile() 内部已处理文件移动操作，因此无需再手动调用 $file->store() 或 ->move()。

Storage::url() 生成的链接无效？检查磁盘类型与符号链接

调用 Storage::url('avatars/abc.jpg') 后，获得类似 /storage/avatars/abc.jpg 的链接，但在浏览器中访问却返回 404。这通常不是代码缺陷，而是部署环境问题。

Laravel 的 url() 方法仅对特定类型的磁盘有效：一种是配置了 'url' 键的 local 类型磁盘（如默认的 public 磁盘），另一种是 s3 等云存储。而默认的、根目录位于 storage/app 的 storage 磁盘（同为 local 类型）并不支持 url()，强行调用会抛出异常。

• 首先确认您正在使用 public 磁盘：检查配置文件中的 'disks.public.root' 是否指向 public_path('storage')，并确保已执行 php artisan storage:link 命令。
• storage:link 命令创建的是从 public/storage 到 storage/app/public 的符号链接。因此，您的文件必须存储到 public 磁盘对应的目录下（通常是 public/ 的子目录），此链接方能生效。
• 最后，Web 服务器配置也需正确。Apache 需开启 mod_rewrite 模块，Nginx 则需正确配置类似 location /storage { alias ...; } 的规则，否则静态资源路由无法正确解析。

总结而言，最关键的一点是：磁盘配置、符号链接路径与 Web 服务器路由三者必须精确匹配。任何一个环节出错，url() 返回的链接都将无法正常访问。