Laravel 9上传存储图片后无法访问显示问题及正确路径写法

问题复现场景 #

• 运行环境：Laragon 集成 Apache、Laravel 9、PHP 8
• 上传功能实现逻辑：控制器中调用storeAs方法将上传图片存到public/id路径，文件实际落盘位置为storage/public/id/test.jpg
• 已执行php artisan storage:link命令创建存储软链接
• 最初视图中使用如下代码渲染图片，始终加载失败，直接访问https://test-project.local/public/id/test.jpg返回404

<img src="{{ asset('public/id/test.jpg') }}" alt="image">

• 将路径调整为{{ asset('storage/id/test.jpg') }}后，图片可正常加载

核心原因 #

这个是Laravel文件存储的高频踩坑点，本质是没搞懂软链接的路径映射规则：

1. Laravel默认的public磁盘，物理文件的存储位置是项目下的storage/app/public/目录，这个目录不在Web服务器配置的对外访问根目录范围内，默认无法直接通过HTTP请求访问
2. php artisan storage:link命令的作用，是在项目的对外Web根目录（也就是站点配置指向的项目public文件夹）下，生成一个名为storage的软链接，直接映射到storage/app/public/目录
3. 所有存到public磁盘的文件，对外HTTP访问的统一前缀是/storage，和物理存储路径里的public目录名没有关联

之前写法里的asset('public/id/test.jpg')，实际是在查找Web根目录下的public/id/test.jpg物理文件，这个路径下根本没有存储上传的文件，自然返回404。

正确写法参考 #

原有控制器上传逻辑不需要调整：

//testing uploads
$extension = $request->file('test_img')->extension();

$path = $request->file('test_img')->storeAs(
    'public/id', 'test.'.$extension
);

视图层渲染有两种规范写法：

1. 手动写路径前缀，注意统一用storage作为前缀

<img src="{{ asset('storage/id/test.jpg') }}" alt="image">

2. 调用Laravel内置的URL生成方法，自动处理路径前缀，后续调整磁盘配置时不需要批量修改视图代码

{{-- 直接传入storeAs返回的$path变量即可，自动生成正确访问地址 --}}
<img src="{{ Storage::url($path) }}" alt="image">

补充排查点：如果执行storage:link后依然访问报错，优先检查项目public目录下的storage软链接是否有效，Windows环境下权限不足时可能生成失效的快捷方式，删除后重新执行命令即可。

内容的提问来源于stack exchange，提问作者DingRealT