ThinkPHP 5.1 的 Filesystem 基于 Flysystem v1，同步阻塞、无重试与并发控制，适合小文件和本地存储；TP6 升级至 v2 但默认无缓存；TP8 移除内置封装，改用 spatie/flysystem-wrapper 轻量桥接。
ThinkPHP 5.1 的 Filesystem 基于 League\Flysystem v1，不支持异步或并发写入
TP5.1 把 think\Filesystem 当作门面，底层实际调用的是 League\Flysystem\Filesystem v1.x。这意味着你用 put()、write() 写文件时，是同步阻塞的，没有内置重试、断点续传或并发控制。
- 常见错误现象：
put()在写大文件（如 >50MB）时超时，Nginx 或 PHP-FPM 直接返回 504；上传中途失败不会自动回滚 - 使用场景：适合小文件读写、本地磁盘（
local）驱动，或简单对象存储（如阿里云 OSS）代理 - 参数差异：v1 的
put()第二个参数是字符串内容，不能直接传resource或StreamInterface；想传流得先用writeStream() - 兼容性影响：v1 不支持
listContents($path, $recursive)的递归深度控制，$recursive = true就是全量扫描，目录深了会卡死
ThinkPHP 6.x 的 Filesystem 升级到 Flysystem v2，但默认没启用缓存和适配器链
TP6.0+ 默认集成 league/flysystem v2，接口更严格，比如 read() 必须返回字符串，readStream() 才返回资源。但框架本身没帮你配好缓存层（CacheAdapter）或多后端路由（MountManager），得自己补。
- 常见错误现象：连续多次
has()+get()查同一个文件，反复走网络请求（尤其 OSS/S3）；getMimetype()对某些驱动返回空，因为 v2 要求驱动显式实现visibility和mimeType探测 - 使用场景：适合需要多存储切换（如开发用 local，生产切 minio）、或要对接新版云厂商 SDK 的项目
- 性能影响：v2 默认关闭元数据缓存，
lastModified()、fileSize()每次都发 HTTP HEAD 请求；加CacheAdapter可降 70%+ IO - 配置要点：必须手动在
filesystem.php里给驱动加'cache' => ['store' => 'redis']，否则缓存不生效
ThinkPHP 8.x 移除了内置 Filesystem，改用 spatie/flysystem-wrapper 作轻量桥接
TP8 彻底放弃封装 Flysystem，转而推荐 spatie/flysystem-wrapper —— 它只是把 v2/v3 的 Filesystem 实例包一层，提供统一构造方式，不新增方法，也不处理异常语义。
- 常见错误现象：升级 TP8 后，原来 TP6 里写的
$this->app->filesystem->disk('oss')->url()报错，因为url()是 TP 自己加的扩展方法，Spatie 包里根本没有 - 使用场景：新项目想最小依赖、或团队已熟悉原生 Flysystem API；老项目迁移需逐个替换
url()、temporaryUrl()等 TP 特有方法 - 参数差异：TP8 的
config/filesystem.php里不再有disks.oss.url配置项，生成 URL 得靠驱动自身（如S3Adapter的getTemporaryUrl()）或自己拼 - 兼容性注意：v3 的 Flysystem 已废弃
listContents()，改用listObjects()+ 迭代器，TP8 的 wrapper 不做兼容转换
跨版本迁移时最易被忽略的三点
不是语法改了才叫 breaking change，真正掉坑里的是那些“看起来能跑，但行为变了”的地方。
立即学习“PHP免费学习笔记（深入）”；
-
setVisibility()在 TP5.1 返回布尔值，在 TP6+ 返回 void；但如果你没检查返回值，旧代码里用if ($fs->setVisibility(...))会永远走 false 分支 - TP5.1 的
copy()支持跨驱动（local → oss），TP6+ 默认不允许，报Unable to copy across filesystems，得用readStream()+writeStream()手动中转 - 所有版本的
deleteDirectory()都是递归删除，但 TP5.1 对空目录可能静默失败，TP6+ 会抛DirectoryNotEmptyException，没 try/catch 就崩
