PHP原生不支持异步文件IO，file_get_contents/file_put_contents底层调用阻塞式read()/write()系统调用，导致请求卡住；可行异步方案仅三条：pcntl_fork子进程、消息队列解耦、Swoole协程文件API。
PHP 本身不支持原生异步文件 IO，所谓“异步 IO”必须依赖扩展或外部服务，直接调用 fopen/file_put_contents 永远是同步阻塞的。
为什么 file_get_contents 和 file_put_contents 会卡住整个请求
这两个函数底层调用的是 POSIX read() 和 write() 系统调用，在磁盘忙或文件大时会真实等待 IO 完成。哪怕只是写入一个 1MB 日志，若磁盘队列已满，PHP 进程就会挂起，无法响应其他逻辑。
- 现象：
top中%wa（iowait）持续高于 15%，strace -p [pid]显示进程长期停在write(3, ...) - 场景：批量导出 CSV、每请求写审计日志、临时生成缩略图并保存
- 关键点：它们不区分“是否必须立刻落盘”——
file_put_contents($f, $data, LOCK_EX)默认就是同步写，且加锁进一步放大排队时间
真正可行的“异步”路径只有三条
不是所有“看起来不卡”的操作都算异步；只有让 PHP 主线程不等待磁盘完成才算数。
-
用
pcntl_fork派生子进程写文件：父进程立即返回，子进程在后台执行file_put_contents。注意需清理僵尸进程，且不适合高并发（fork 开销大） -
投递到消息队列（如 Redis List + worker）：主流程只做
$redis->rPush('io_jobs', json_encode([...]))，由独立 PHP worker 进程消费并写盘。这是最稳定、可监控、可伸缩的方案 -
借助 Swoole 的异步文件 API：仅限启用
swoole.enable_coroutine=1的协程环境，使用Swoole\Coroutine\FileSystem::writeFile()或openFile()。它把系统调用封装为协程让出点，不阻塞其他协程，但本质仍是同步 IO，只是调度更细粒度
别被 Guzzle Promises 带偏：它只管 HTTP，不管文件
guzzlehttp/promises 解决的是多个 curl 请求之间的并发与编排问题，和本地文件读写完全无关。你在 then() 里调用 file_put_contents，Promise 并不会让它变快——那个写操作依然会堵住当前协程/线程。
立即学习“PHP免费学习笔记（深入）”；
- 错误用法：
$p = \GuzzleHttp\Promise\resolve()->then(fn() => file_put_contents('log.txt', 'x'))→ 日志还是同步写，Promise 只是包装了时机，没改变 IO 模型 - 正确思路：Promise 可以串起「发 HTTP 请求 → 收到响应 → 把结果推给 Redis 队列」，把文件 IO 推离主请求链路
- 兼容性注意：Swoole 协程下混用
file_put_contents和协程文件 API 会导致死锁，必须统一用协程版
最容易被忽略的性能断点：file_exists 的 stat 飙升
大量文件操作常伴随高频 file_exists() 判断，而每次调用都触发一次 stat() 系统调用。当目录下有上万文件时，ext4 的目录查找可能退化为线性扫描，单次 file_exists 耗时从微秒级跳到毫秒级。
- 现象：
strace显示大量重复stat("uploads/xxx.jpg", {...}) = 0，且耗时波动极大 - 解法：用
opcache.stat = 0关闭 OPCache 对脚本文件的自动检查（不影响业务文件）；对业务路径，改用内存缓存路径存在性，比如$cache["exists:{$path}"] = true，TTL 设为 60 秒 - 硬核替代：若确定文件只增不删，可用
scandir()一次性读全目录名进内存做in_array()查找，比一万次stat快一个数量级
