直接用 Storage 出错因默认驱动路径不匹配，需手动创建 Filesystem 实例并显式构造绝对路径；删除非空目录应手动遍历而非依赖 deleteDirectory()；封装推荐组合而非继承。
为什么直接用 Storage 有时会出错？
因为 Laravel 的 Storage facade 默认走的是配置的默认驱动（通常是 local），但实际项目中常要操作非配置路径（比如临时上传目录、第三方挂载盘、或需绕过 Flysystem 封装的 raw 文件操作）。这时候直接调用 Storage::put() 可能写到错位置，甚至因权限/符号链接问题静默失败。
常见错误现象：file_put_contents(): No such file or directory，但 Storage::disk('local')->path('xxx') 返回的路径却存在——说明是 Flysystem 层做了路径拼接或根目录偏移。
- 检查当前 disk 配置的
root是否含末尾斜杠（缺了会导致路径拼接异常） - 避免在
public目录外用publicdisk，它默认只允许访问public_path()下子路径 - 需要绝对路径操作时，别依赖
Storage::disk()->path()，改用realpath()或base_path()显式构造
Filesystem 实例怎么手动创建并复用？
Laravel 的 Storage 是 facade，背后是 Illuminate\Filesystem\Filesystem 实例。想脱离配置、精准控制路径和行为，就该直接 new 它，而不是总查 config/filesystems.php。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 用
new Illuminate\Filesystem\Filesystem创建裸实例，传入 PHP 原生FilesystemIterator不支持的底层逻辑由它补全（如递归删除、空目录判断） - 若需支持 symlink、chmod、owner 等系统级操作，优先调
file_put_contents()/unlink()等原生函数，Filesystem类不封装这些 - 封装成 service 时，把 root 路径作为构造参数传入，而非硬编码
storage_path()，方便测试 mock
示例：
$fs = new \Illuminate\Filesystem\Filesystem(); $fs->copy($source, $dest); // 安全复制（自动创建父目录） $fs->isDirectory($path); // 比 is_dir() 多一层 realpath 判断
如何安全地删除非空目录？
Filesystem::deleteDirectory() 看似方便，但在某些 Linux 环境（如容器内 uid/gid 不匹配）会卡在只读文件或权限拒绝，且不抛异常，只返回 false。
更稳的做法：
- 先用
scandir()+array_filter()手动遍历，对每个项分别处理：文件用unlink()，目录递归调自己 - 删前加
clearstatcache(true, $path)，避免因 stat 缓存导致is_dir()判定失准 - 若目录含大量小文件，避免用
Filesystem::cleanDirectory()（它内部用glob()，易爆内存）
关键点：Laravel 的 deleteDirectory() 不等价于 shell 的 rm -rf，它不会跳过权限错误，也不会自动 chmod。
封装时要不要继承 Filesystem？
不要。Laravel 8+ 已将 Filesystem 设为 final，且其方法多为工具型（无状态），继承既无必要又增加耦合。
推荐方式：
- 写一个
FileHelper类，构造时注入Filesystem实例 + 自定义 root（如app_path('temp')） - 方法命名直白：比如
moveToArchive($file, $archiveDir)，内部组合$this->fs->exists()+$this->fs->makeDirectory()+rename() - 对「可能失败」的操作（如解压 zip、生成缩略图），统一返回
Result对象（含success、message、path），别让调用方自己 try/catch
复杂点在于：很多「文件操作」其实不是纯 IO，还牵扯到事件触发（如上传完成发通知）、事务一致性（如写完文件再更新 DB）、以及并发锁（多个请求同时写同一临时文件）。这些没法靠封装一个类解决，得结合 Cache::lock() 和 DB transaction 才算闭环。
