Hyperf 3.0 中协程文件读写必须使用 Swoole 协程 I/O 接口，禁用 file_get_contents 等同步函数，否则阻塞协程调度器导致服务不可用；应改用 Co\File::read、Co\Stream\Stdio 分块读写，并确保 swoole.enable_coroutine=On。
Hyperf 3.0 中协程文件读写必须避开同步阻塞操作，否则会直接卡死协程调度器——这不是性能问题，而是服务可用性问题。
为什么 file_get_contents、fopen 等会破坏协程
这些函数底层调用的是 PHP 原生同步 I/O，会阻塞当前协程线程，导致调度器无法切换其他协程。此时 swoole_get_local_cid() 返回 -1，进程看似“活着”，实则已脱离协程上下文，新请求无法被处理。
- 常见误用：在协程中直接调用
file_get_contents读取大文件、file_put_contents写入日志、curl_exec同步请求 - 隐蔽风险：某些 SDK（如旧版 Redis 扩展、自定义文件工具类）的
__construct或connect方法内部隐含stream_socket_client同步调用 - 验证方式：用
strace -p <pid>观察是否长期停在read或epoll_wait且无后续系统调用
协程安全的文件读写替代方案
核心原则是使用 Swoole 提供的协程化 I/O 接口，或通过流式操作配合 Co\Stream\Stdio 控制读写节奏。
- 小文件读取：用
Co\File::read($path)替代file_get_contents - 大文件分片读取：用
$stream = new Co\Stream\Stdio($fp)+$stream->read(8192)分块读，避免内存暴涨 - 写入临时文件：先用
fopen(..., 'w')创建句柄，再用Co\Stream\Stdio包装后写入，或直接用Co\File::writeFile - 校验文件完整性：必须用
Co\File::md5_file($path)，而非md5_file()，后者是同步阻塞的
关键配置与检查项
光换函数不够，还需确认运行环境真正支持协程 I/O。
- 确保
php.ini中未手动关闭协程：swoole.enable_coroutine = On（Hyperf 默认开启，但某些部署脚本可能覆盖） - 禁用所有
ini_set('swoole.enable_coroutine', '0')类逻辑，Hyperf 依赖全程协程环境 - 检查 vendor 中第三方包是否声明支持 Swoole 协程，重点关注其连接初始化、文件操作等生命周期方法
- 日志写入建议用 Monolog 的
BufferHandler + RotatingFileHandler异步缓冲，避免高频fwrite成为瓶颈
调试与定位阻塞点的实用方法
出问题时，快速锁定哪个协程、哪行代码在阻塞。
- 在中间件或异常捕获处插入诊断代码，遍历
Coroutine::listCoroutines()，筛选状态为SWOOLE_CORO_WAITING的协程 - 对 WAITING 协程调用
Coroutine::getBackTrace($cid, 0, 10)，重点看堆栈末尾是否出现stream_select、socket_read、fgets等同步调用 - 触发协程快照：
kill -USR1 <worker_pid>，Swoole 自动将快照写入/tmp/swoole-coroutine-*.log，检查其中的阻塞调用链 - 临时加日志：在可疑文件操作前后打印
Coroutine::id()和时间戳，确认是否“进去就出不来”
