Flysystem 的核心陷阱是勿将其当黑盒：它不处理鉴权、无自动重试、不保证原子写入；write() 可能假成功，应改用 writeStream() 并校验；listContents() 默认不递归且忽略伪目录；替换文件须用临时名+move；各适配器对文件/目录语义差异大，需查底层 SDK。
PHP 用 Flysystem 处理文件系统，核心不是“怎么抽象”，而是“别让 Flysystem 变成黑盒”——它本身不处理鉴权、不自动重试、不保证原子写入，直接套用默认配置上线容易在并发或异常时丢文件。
为什么 write() 有时成功却读不到文件？
Flysystem 的 write() 默认不校验写入完整性，尤其在 S3 或 OSS 等对象存储后端，网络中断可能导致“返回成功但实际只传了部分数据”。更隐蔽的是本地适配器（如 LocalFilesystemAdapter）在 NFS 挂载点上可能因缓存延迟导致 has() 返回 false。
- 始终用
writeStream()替代write()，传入fopen($path, 'rb')流，避免内存中拼接大文件 - 写完立刻调用
read()或fileSize()做轻量验证（注意：S3 的fileSize()是 HEAD 请求，开销低） - 本地开发时禁用 opcache 文件状态缓存：
opcache.enable_file_override=0，否则has()可能命中过期 stat 缓存
listContents() 返回空数组但文件明明存在？
这是 Flysystem v3 最常被踩的坑：目录列表默认不递归，且不包含“伪目录”（即只有前缀无实际 / 结尾的对象）。比如上传了 logs/app-2024-01.log，listContents('logs') 在 S3 适配器下大概率为空，因为 S3 根本没有 logs/ 这个对象，只有键名带前缀的文件。
- 显式传参：
listContents('logs/', true)（第二个参数为true表示递归） - 确认适配器是否支持目录模拟：S3 适配器需设置
'directory_listing' => true，OSS 适配器则必须依赖prefix+delimiter='/'手动拼接 - 避免用
listContents('')查根目录——某些云存储会限制空前缀请求，改用listContents('/')或具体路径
如何安全替换已存在文件？
Flysystem 没有原子性的 replace()，write() 对已有文件是覆盖，但覆盖过程非原子：旧文件可能短暂消失，新文件写到一半又失败，导致数据丢失。生产环境绝不能依赖 write() 直接覆盖关键配置或用户上传文件。
立即学习“PHP免费学习笔记（深入）”；
- 用临时名写入：
write('temp_'.$uniqid.'.json', $data)，再move('temp_xxx.json', 'config.json') - 移动操作在本地适配器是原子的（rename），在 S3 是先 copy 后 delete，需确认目标桶开启版本控制以防 delete 失败丢失旧版
- 若业务要求强一致性，绕过 Flysystem 直接调用底层 SDK 的
putObject并启用ServerSideEncryption参数（Flysystem 抽象层不透传加密配置）
真正难的不是调通 Filesystem 实例，而是搞清每个适配器对“文件”“目录”“存在性”的定义差异——S3 没有目录，FTP 可能返回乱码路径，WebDAV 的 lastModified() 精度只有秒级。别把抽象层当万能胶，该查原始 SDK 文档时就得查。
