Laravel8中Cloudinary图片本地img标签正常 Heroku生产环境空白如何解决

架构老林

2026-9-26

Laravel 8 Cloudinary 生产环境图片路径丢失问题排查

问题诱因

生产环境环境变量缺失：Heroku 实例未配置 FILESYSTEM_DRIVER 或 CLOUDINARY_URL 两个核心环境变量，Laravel 默认使用本地 public 磁盘存储逻辑，仅返回相对路径而非 Cloudinary 完整远程路径
配置缓存未更新：Laravel 生产环境会缓存配置文件，若部署时未清理旧缓存，即使新增了环境变量也不会生效，依旧读取旧的本地磁盘配置
Cloudinary SDK 初始化失败：缺少 CLOUDINARY_URL 配置时，Cloudinary 扩展包无法正常初始化，生成资源链接时仅返回上传后的文件名，不会拼接远程服务前缀

可行解决方法

核对 Heroku 环境变量
执行 heroku config 命令确认实例已配置以下变量，值和本地开发环境保持一致：
- CLOUDINARY_URL：Cloudinary 控制台获取的完整授权连接串
- FILESYSTEM_DRIVER：Laravel 8 需设置为 cloudinary，指定默认存储磁盘为 Cloudinary

确认文件系统配置

检查 config/filesystems.php 中已正确添加 Cloudinary 磁盘配置：

'disks' => [
    // 其他磁盘配置
    'cloudinary' => [
        'driver' => 'cloudinary',
        'url' => env('CLOUDINARY_URL'),
        'root' => env('CLOUDINARY_ROOT', '/'),
        'throw' => false,
    ],
]

同时确保代码中获取图片 URL 时使用官方方法，不要手动截断路径：

// 正确用法
$imgUrl = Storage::disk('cloudinary')->url($fileName);

刷新生产环境配置缓存
在 Heroku 项目的 Procfile 中添加 release 阶段命令，每次部署自动刷新配置缓存：
```
release: php artisan config:cache
web: vendor/bin/heroku-php-apache2 public/
```
也可以手动执行 heroku run php artisan config:cache 立即刷新缓存
兜底手动拼接路径
若上述配置都正确仍存在问题，可以在环境变量中新增 Cloudinary 固定前缀：
```
CLOUDINARY_BASE_URL=https://res.cloudinary.com/你的Cloudinary用户名/image/upload
```
输出时手动拼接路径：
```
$imgUrl = env('CLOUDINARY_BASE_URL') . '/' . $fileName;
```