Laravel 图片无法从 storage 目录显示的完整解决方案-php教程-PHP中文网

Laravel 图片无法从 storage 目录显示的完整解决方案

Laravel 项目迁移或重装后，通过 storage:link 创建的软链接可能失效或被缓存，导致 storage/app/public/ 下的图片无法通过 asset('storage/...') 正确访问；本文提供清除缓存、重建链接并验证路径的标准化解决流程。

laravel 项目迁移或重装后，通过 `storage:link` 创建的软链接可能失效或被缓存，导致 `storage/app/public/` 下的图片无法通过 `asset('storage/...')` 正确访问；本文提供清除缓存、重建链接并验证路径的标准化解决流程。

在 Laravel 中，将用户上传的图片等文件存放在 storage/app/public/ 目录下，并通过 php artisan storage:link 创建指向 public/storage 的符号链接，是官方推荐的公开资源托管方式。但当项目被整体删除重建（如从备份恢复、克隆新副本或部署到新环境）时，常出现图片“明明存在却 404”的问题——即使终端提示 The [public/storage] link has been connected，浏览器仍无法加载图片。

根本原因在于：
✅ public/storage 软链接本身可能残留旧路径或损坏；
✅ Laravel 的配置/路由/视图编译缓存（如 bootstrap/cache/config.php、routes-v7.php 或 OPCache）可能仍引用旧链接状态；
✅ 前端 asset() 辅助函数生成的 URL 依赖于当前有效的 public/storage 链接，一旦链接异常，URL 就会指向 404 路径。

✅ 正确修复步骤（按顺序执行）

手动删除旧链接
进入项目根目录，删除已存在的 public/storage：
```
rm -f public/storage
```
⚠️ 注意：仅删除链接本身，不要删除 storage/app/public/ 中的真实文件！

彻底清空所有缓存
执行以下命令清除配置、路由、视图及优化缓存：

php artisan optimize:clear

该命令等效于依次运行：

php artisan config:clear
php artisan cache:clear
php artisan route:clear
php artisan view:clear
php artisan clear-compiled

重新创建存储链接

php artisan storage:link

成功输出应为：

The [public/storage] link has been connected to [storage/app/public].

验证链接有效性
在终端中检查链接是否正确指向：
```
ls -la public/storage
# 应输出类似：public/storage -> ../storage/app/public
```
同时，确保目标路径下存在对应图片，例如：

Laravel Cloud
Laravel Cloud（cloud.laravel.com）。此技能用于处理所有 Laravel Cloud 请求，包括搜索和读取数据。只要任务涉及 Laravel Cloud，即使用此技能。

下载
```
ls -l storage/app/public/uploads/product_1.jpg
```
修正代码中的路径拼接（推荐更健壮写法）
您当前的写法存在潜在风险：
```
$imgUrl = asset('storage' . str_replace('public', '', $submission->image_path));
```
若 $submission->image_path 是 storage/app/public/uploads/photo.jpg，str_replace('public', '') 会错误地变成 storage/app//uploads/photo.jpg（双斜杠），且逻辑耦合过强。

✅ 推荐使用 Laravel 内置的 Storage 门面 + url() 方法（需确保 config/filesystems.php 中 public 磁盘已配置为 'driver' => 'local' 且 'root' => storage_path('app/public')）：
```
->editColumn('image_path', function ($submission) {
    // 假设 $submission->image_path 存储的是相对路径，如 'uploads/photo.jpg'
    $path = ltrim($submission->image_path, 'storage/app/public/');
    $url = Storage::disk('public')->url($path);
    return "@@##@@";
})
```
或更简洁地（若数据库中只存相对路径）：
```
->editColumn('image_path', function ($submission) {
    return "@@##@@image_path) . "\" alt=\"Gambar Barang\" width=\"250\" />";
})
```
✅ 此时 $submission->image_path 应为 uploads/photo.jpg（不含 storage/app/public/ 前缀），asset('storage/uploads/photo.jpg') 将自动解析为 /storage/uploads/photo.jpg，由 public/storage 链接正确映射。