Laravel使用Homestead时出现Storage path is not part of public path错误如何解决

核心问题 #

报错的触发原因是Laravel的存储路径合法性校验逻辑：当你使用public磁盘存储文件时，系统会校验存储根目录是否和软链接映射的路径匹配，你之前的磁盘配置违反了Laravel默认的存储目录规范。

分步操作 #

1. 修正filesystems.php配置 #

将disks数组重置为官方规范配置：

'disks' => [
    'local' => [
        'driver' => 'local',
        'root' => storage_path('app'),
    ],
    'public' => [
        'driver' => 'local',
        'root' => storage_path('app/public'),
        'url' => env('APP_URL').'/storage',
        'visibility' => 'public',
    ],
    's3' => [
        // 保持原有配置不变
    ],
],

注意：你此前将public磁盘的root参数设为public_path开头的路径，相当于把存储目录直接放在public文件夹下，和storage:link生成的软链接逻辑完全冲突，这是报错的核心原因。

2. 清理缓存与旧软链接 #

必须在Homestead虚拟机内部的项目根目录执行以下命令，不要在宿主机本地执行：

# 删除无效旧软链接
rm -rf public/storage
# 清理所有缓存
php artisan config:clear
php artisan cache:clear
# 重新生成软链接
php artisan storage:link

3. 校验软链接与权限 #

执行ls -la public查看软链接指向，正常输出应为：
storage -> /home/vagrant/code/soso-api/storage/app/public
如果指向错误可以手动创建软链接：

ln -s /home/vagrant/code/soso-api/storage/app/public /home/vagrant/code/soso-api/public/storage

最后赋予存储目录正确权限：

chmod -R 755 storage bootstrap/cache

4. Windows宿主机特殊处理 #

如果你是Windows系统运行Homestead，需要以管理员权限打开终端再执行vagrant up，否则共享文件夹下无法正常创建软链接，会持续触发路径错误。

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