Laravel 9在Cpanel共享主机中Storage链接图片出现404错误

本地开发基于Laravel 9（PHP 8）的项目时，图片可正常上传至storage文件夹，通过asset('storage/' . $user->profile_pic)生成的URL能正常访问图片。将项目部署到Cpanel共享主机后，已执行php artisan storage:link命令建立storage与public/storage的软链接，图片可正常上传至服务器（已通过public/storage文件夹验证），但使用相同方式生成图片URL访问时，服务器返回404页面未找到错误。

相关配置代码 #

filesystem.php 文件 #

return [

    /*
    |--------------------------------------------------------------------------
    | Default Filesystem Disk
    |--------------------------------------------------------------------------
    |
    | Here you may specify the default filesystem disk that should be used
    | by the framework. The "local" disk, as well as a variety of cloud
    | based disks are available to your application. Just store away!
    |
    */

    'default' => env('FILESYSTEM_DISK', 'local'),

    /*
    |--------------------------------------------------------------------------
    | Filesystem Disks
    |--------------------------------------------------------------------------
    |
    | Here you may configure as many filesystem "disks" as you wish, and you
    | may even configure multiple disks of the same driver. Defaults have
    | been set up for each driver as an example of the required values.
    |
    | Supported Drivers: "local", "ftp", "sftp", "s3"
    |
    */

    'disks' => [

        'local' => [
            'driver' => 'local',
            'root' => storage_path('app'),
            'throw' => false,
        ],

        'public' => [
            'driver' => 'local',
            'root' => storage_path('app/public'),
            'url' => env('APP_URL').'/storage',
            'visibility' => 'public',
            'throw' => false,
        ],

        '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),
            'throw' => false,
        ],

    ],

    /*
    |--------------------------------------------------------------------------
    | Symbolic Links
    |--------------------------------------------------------------------------
    |
    | Here you may configure the symbolic links that will be created when the
    | `storage:link` Artisan command is executed. The array keys should be
    | the locations of the links and the values should be their targets.
    |
    */

    'links' => [
        public_path('storage') => storage_path('app/public'),
    ],

];

测试用控制器函数 #

public function test(Request $request)
{
    
    // decode the base64 image
    $base64File = request('profile_pic');
    $fileData = base64_decode($base64File);

    $name = 'users_profile/' . Str::random(15) . '.png';
    
    Storage::put('public/' . $name, $fileData);
    // update the user's profile_pic
    echo asset('storage/' . $name);

}

Cpanel上的.env 文件 #

APP_NAME=Laravel
APP_ENV=local
APP_KEY=base64:{}
APP_DEBUG=true
APP_URL={myurl}

LOG_CHANNEL=stack
LOG_DEPRECATIONS_CHANNEL=null
LOG_LEVEL=debug

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE={my Databse}
DB_USERNAME={my user name}
DB_PASSWORD={my password}

BROADCAST_DRIVER=log
CACHE_DRIVER=file
FILESYSTEM_DISK=local
QUEUE_CONNECTION=sync
SESSION_DRIVER=file
SESSION_LIFETIME=120

MEMCACHED_HOST=127.0.0.1

REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379

MAIL_MAILER=smtp
MAIL_HOST=mailhog
MAIL_PORT=1025
MAIL_USERNAME=null
MAIL_PASSWORD=null
MAIL_ENCRYPTION=null
MAIL_FROM_ADDRESS="hello@example.com"
MAIL_FROM_NAME="${APP_NAME}"

AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=
AWS_DEFAULT_REGION=us-east-1
AWS_BUCKET=
AWS_USE_PATH_STYLE_ENDPOINT=false

PUSHER_APP_ID=
PUSHER_APP_KEY=
PUSHER_APP_SECRET=
PUSHER_HOST=
PUSHER_PORT=443
PUSHER_SCHEME=https
PUSHER_APP_CLUSTER=mt1

VITE_PUSHER_APP_KEY="${PUSHER_APP_KEY}"
VITE_PUSHER_HOST="${PUSHER_HOST}"
VITE_PUSHER_PORT="${PUSHER_PORT}"
VITE_PUSHER_SCHEME="${PUSHER_SCHEME}"
VITE_PUSHER_APP_CLUSTER="${PUSHER_APP_CLUSTER}"

解决方法 #

1. 验证软链接有效性 #

Cpanel环境下，Artisan创建的软链接可能因路径权限或主机限制失效：

• 通过Cpanel文件管理器手动创建：进入public目录，新建符号链接，目标路径设为../storage/app/public
• 或SSH执行命令（替换为你的实际主机路径）：

  ln -s /home/your_username/storage/app/public /home/your_username/public_html/storage
  

2. 修正APP_URL配置 #

确保.env中的APP_URL为完整域名（如https://yourdomain.com），无多余斜杠或错误前缀。

3. 使用Storage门面生成URL #

替换手动拼接asset()的方式，改用Laravel官方推荐的方法：

// 存储时指定public磁盘
Storage::disk('public')->put($name, $fileData);
// 生成正确访问URL
echo Storage::url($name);

此方法会自动结合filesystem.php中public磁盘的url配置生成路径，避免手动拼接错误。

4. 检查目录权限 #

确保storage/app/public和public/storage目录权限为755，文件权限为644，避免因权限不足导致无法访问。

5. 刷新配置缓存 #

执行以下命令清除缓存，确保配置更改生效：

php artisan config:clear
php artisan cache:clear

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