Laravel Voyager子域名部署后托管环境图片无法显示

故障现象 #

• Voyager项目部署在子域名https://sub.domainname.com上，本地开发环境图片上传、展示功能均正常，迁移至主机托管环境后，所有上传的图片均显示为破损状态，媒体管理菜单中刚完成上传的图片也直接呈现破损效果。

现有配置信息 #

1. 环境变量APP_URL配置 #

APP_URL=https://sub.domainname.com

2. 文件系统配置（config/filesystems.php） #

'disks' => [
    'local' => [
        'driver' => 'local',
        'root' => storage_path('app'),
    ],
    'public' => [
        'driver' => 'local',
        'root' => storage_path('app/public'),
        'url' => env('APP_URL').'/storage',
        'visibility' => 'public',
    ],
    's3' => [
        'driver' => 's3',
        'key' => env('AWS_ACCESS_KEY_ID'),
        'secret' => env('AWS_SECRET_ACCESS_KEY'),
        'region' => env('AWS_DEFAULT_REGION'),
        'bucket' => env('AWS_BUCKET'),
        'url' => env('AWS_URL'),
        'endpoint' => env('AWS_ENDPOINT'),
        'use_path_style_endpoint' => env('AWS_USE_PATH_STYLE_ENDPOINT', false),
    ],
],

故障参考截图 #

排查解决步骤 #

按以下优先级逐一排查，90%以上的同类问题在前两步即可解决：

1. 生成/修复storage软链
   Laravel public磁盘的文件对外访问依赖public/storage到storage/app/public的软链接，迁移环境后软链丢失、路径错误是这类问题的最高发原因。

   • 有服务器SSH权限的场景，进入项目根目录执行命令重新生成软链：

     php artisan storage:link
     

   • 无SSH权限的共享主机场景，可临时在项目public/index.php入口文件中加入如下代码，访问一次站点触发软链生成后，立刻删除该临时代码：

     \Illuminate\Support\Facades\Artisan::call('storage:link');
     

   • 注意：如果子域名实际指向项目子目录而非public目录，必须使用相对路径生成软链，绝对路径软链在该场景下会直接失效。

2. 校验目录权限与文件实际存在性

   • 上传测试图片后，先到服务器storage/app/public对应上传目录下确认文件是否真实写入，如果文件不存在，说明上传环节失败，先把storage目录及其所有子目录权限调整为755，保证Web运行用户（常见为www-data、www、nginx）对目录有写入权限。
   • 如果文件存在，确认public目录、storage目录的所有者与Web服务运行用户一致，避免Web服务无权读取文件导致访问失败。

3. 验证图片访问路径与Web服务规则

   • 右键点击页面上的破损图片，复制图片地址直接在浏览器打开，根据返回结果定位问题：
     • 返回404：首先回到第一步重新检查软链有效性，其次检查Web服务重写规则，确认Nginx/Apache没有把/storage/*路径的静态资源请求全部rewrite到index.php，要保留静态文件直接读取的规则。
     • 返回403：除了权限问题，还要检查PHP的open_basedir配置是否包含项目storage目录，部分虚拟主机会默认限制跨目录访问。
     • 访问路径与配置的APP_URL不匹配：执行如下命令清除Laravel缓存的旧配置即可：

       php artisan config:clear
       php artisan cache:clear
       

4. 托管环境特殊规则排查

   • 部分虚拟主机会默认禁止storage目录的公开访问，需要到主机控制面板将public/storage目录设置为公开可访问状态，或在目录下添加对应服务的访问规则文件（Apache环境添加.htaccess、IIS环境添加web.config）。
   • 如果站点开启了CDN或WAF，检查回源规则是否拦截了/storage路径的静态资源请求，是否存在安全规则误拦截图片资源的情况。

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