在 Laravel 项目中处理用户上传的图片，并能在 Blade 模板里正常展示，是后台管理、社交类应用的基础需求。不少人在实现时把文件存到了 storage 目录下，却忘了配置公开访问机制，导致前端一直加载不出图片。下面我们先看整体流程涉及的核心环节。
一、理解 Laravel 的文件存储磁盘
Laravel 通过 config/filesystems.php 管理多种磁盘。默认情况下，local 磁盘指向 storage/app，该目录不在 Web 根目录下，浏览器无法直接访问。若要让用户上传的图片可通过 URL 访问，应当使用 public 磁盘，其根目录为 storage/app/public，并且需要在 public 目录下建立软链接 storage 指向它。
很多初学者误以为只要把图片存进 storage 就能用 url() 直接输出，结果返回的路径并不对应真实可访问地址。正确做法是执行 php artisan storage:link 命令，将 public/storage 软链到 storage/app/public。之后所有存入 public 磁盘的文件，都能通过 asset('storage/文件名') 被浏览器加载。
二、接收并存储上传图片
在控制器中，我们通过请求对象的 file() 方法获取上传对象，并利用 storeAs() 指定目录和文件名。务必先校验文件类型与大小，避免恶意脚本或超大文件拖垮服务器。下面是一段典型存储代码：
<?php
// 在控制器方法中处理上传
public function upload(Request $request)
{
// 校验规则
$request->validate([
'avatar' => 'required|image|mimes:jpeg,png,jpg,gif|max:2048',
]);
// 存入 public 磁盘的 avatars 目录，文件名保持原扩展名
$path = $request->file('avatar')->storeAs(
'avatars',
time() . '_' . $request->file('avatar')->getClientOriginalName(),
'public'
);
// 返回存储的相对路径，如 avatars/12345_test.png
return back()->with('path', $path);
}
上面的代码显式传入了第三个参数 public，确保文件落到公开磁盘。若省略该参数，默认写入 local 磁盘，前端将无法访问。storeAs 的第二个参数应避免使用用户原始名而不加处理，防止中文或特殊字符引发存储异常，这里采用时间戳前缀降低冲突概率。
另一种写法是使用 store() 让系统自动生成文件名，但业务常需要可控名称，因此 storeAs 更实用。存储成功后，Laravel 返回的是相对于磁盘根目录的路径，Blade 中需配合辅助函数拼接完整 URL。
三、在 Blade 模板中显示图片
Blade 本质是将数据渲染为 HTML 的模板引擎。显示图片时，绝不可拼接物理绝对路径，而应使用 asset() 基于 public 软链生成地址。以下示例展示如何安全输出：
<!-- resources/views/profile.blade.php -->
<div class="avatar-box">
@if(isset($path))
<img src="{{ asset('storage/' . $path) }}" alt="用户头像" width="120">
@else
<img src="{{ asset('images/default.png') }}" alt="默认头像" width="120">
@endif
</div>
注意代码中 asset('storage/' . $path) 的写法：因为软链使 public/storage 映射至 storage/app/public，所以前缀必须是 storage/ 而非 avatars/ 直接开头。若写成 asset($path) 会丢失 storage 前缀，导致 404。
当 $path 为 avatars/12345_test.png 时，最终 HTML 的 img 的 src 会变为 /storage/avatars/12345_test.png，浏览器向该路径发请求，由 public/storage 软链导向真实文件。若未执行 storage:link，则该 URL 返回 404，页面显示碎图。
四、常见错误与排查
第一类问题是权限不足。在 Linux 环境，storage 目录需允许 Web 服务用户读取，否则即使软链正确也会报 403。可用 chmod -R 755 storage 适当放宽，但应避免 777 这种危险配置。
第二类问题是表单遗漏 enctype="multipart/form-data"。如果 Blade 表单像下面这样写，后端 file() 拿到的是 null：
<form action="/upload" method="POST">
@csrf
<input type="file" name="avatar">
<button type="submit">上传</button>
</form>
正确形式必须声明编码类型，否则文件不会随请求体发送：
<form action="/upload" method="POST" enctype="multipart/form-data">
@csrf
<input type="file" name="avatar">
<button type="submit">上传</button>
</form>
第三类问题是缓存。修改了 filesystems 配置后，需运行 php artisan config:clear 清除配置缓存，否则磁盘映射仍是旧值。结合上述存储与展示方法，即可在 Laravel Blade 中稳定地处理图片上传与显示。
五、小结与扩展
将图片存入 public 磁盘并建立软链，是 Laravel 实现可访问上传资源的标准做法。Blade 中统一用 asset('storage/' . $path) 输出，既隔离了物理路径，也便于以后迁移到云存储。若项目后续使用 OSS 或 S3，只需改 disks 配置，Blade 代码无需变动。
对于多图场景，可把路径数组 json 化存入数据库，在 Blade 中用 @foreach 循环渲染。掌握这套存储加展示机制，便能应对绝大部分 Laravel 图片处理需求，减少因路径错误带来的联调时间消耗。