cPanel环境Laravel9运行symlink未生成storage文件夹如何解决

云原生阿岚

2026-8-26

问题原因

Laravel 9 最低依赖 PHP 8.0+，绝大多数用户升级 Laravel 9 时会同步将主机 PHP 版本从 7.x 升级到 8.x，cPanel 共享主机在新版 PHP 环境下默认启用的两项限制，会直接触发你遇到的问题：

跨目录绝对路径符号链接拦截：如果symlink的目标路径在当前站点根目录（即tlc.musafhanif.com）之外，使用绝对路径创建的链接会被主机安全规则直接拦截，加上PHP默认关闭错误显示，就会出现空白页、无任何报错提示的现象。
升级过程中文件权限/属主变更：通过Composer升级Laravel版本时，若执行命令的用户和PHP运行用户不一致，会导致storage目录、站点public目录的属主变更，PHP没有对应目录的写入/读取权限，symlink会直接执行失败。
另外你当前的测试脚本没有做错误捕获和残留文件清理，旧的断链、残留文件夹也会导致新链接无法创建。

排查步骤

按顺序做基础排查，避免无意义试错：

在测试脚本最顶部开启错误显示，拿到真实报错信息：
```
ini_set('display_errors', 1);
error_reporting(E_ALL);
```
确认两个路径真实存在、权限正确：
- 目标路径/home/cpanelusername/tlcapp/storage/app/public需存在，目录权限设为755，递归将tlcapp/storage、tlcapp/bootstrap/cache目录的权限设为允许PHP读写
- 链接父目录/home/cpanelusername/tlc.musafhanif.com/public需存在，PHP对该目录有写入权限
彻底清理残留无效链接：不要仅通过FTP删除，进入cPanel文件管理器开启「显示隐藏文件」，确认public目录下没有任何名为storage的文件、文件夹、断链；如果有SSH权限可直接执行命令清理：
```
rm -rf /home/cpanelusername/tlc.musafhanif.com/public/storage
```
确认symlink函数可用：在脚本中加一行var_dump(function_exists('symlink'));，如果返回bool(false)说明函数被主机禁用，联系主机商放开即可。

适配Laravel 9的解决方法

优先使用Laravel自带的存储链接功能，不要手动写绝对路径symlink：

无SSH权限的场景，在routes/web.php中添加临时路由，执行完成后立刻删除该路由：

Route::get('/create-storage-link', function () {
    // 自动清理旧的无效链接
    if (file_exists(public_path('storage'))) {
        is_link(public_path('storage')) ? unlink(public_path('storage')) : rmdir(public_path('storage'));
    }
    // 调用Laravel内置命令创建链接
    Artisan::call('storage:link');
    return nl2br("执行结果：\n" . Artisan::output());
});

访问https://你的域名/create-storage-link即可看到执行结果，成功后页面会返回The [public/storage] link has been connected to [storage/app/public].

如果内置命令执行提示权限错误，是主机拦截了绝对路径跨目录symlink，改用相对路径创建即可，替换原有代码为：

// 先切换到站点public目录，保证相对路径计算正确
chdir('/home/cpanelusername/tlc.musafhanif.com/public');
// 目标路径用相对当前public目录的相对路径
$target = '../../tlcapp/storage/app/public';
$link = 'storage';
symlink($target, $link);
echo "符号链接创建完成";

创建完成后验证：访问https://你的域名/storage/任意存在的测试文件，能正常打开就说明配置生效。

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