Swoole 和 Hyperf 不是传统 PHP-FPM 插件，而是常驻内存的协程运行范式；推荐新建 Hyperf 项目而非硬集成旧框架，CLI 场景可谨慎复用 Swoole 特性但须禁用同步 IO 并确保协程安全。
直接在现有 PHP 项目中通过 Composer 集成 Swoole 或 Hyperf 并非“加个包就能跑”，关键在于理解它们的运行模型差异——Swoole 是常驻内存的协程服务器，Hyperf 是基于 Swoole 构建的全异步框架，二者都不走传统 PHP-FPM 流程。强行在 Laravel/ThinkPHP 等同步框架里“局部引入 Swoole 扩展”容易引发阻塞、内存泄漏或协程上下文丢失，不推荐。
明确项目定位：是升级为常驻服务，还是仅复用部分能力？
这是第一步决策：
- 想彻底转向高性能长连接、高并发微服务 → 直接新建 Hyperf 项目，别硬套进旧项目
- 只想在现有项目里用 Swoole 的某些特性（如协程 MySQL、定时器、异步任务） → 可以在 CLI 模式下有限使用，但必须确保不混用同步阻塞调用（如 file_get_contents、curl_exec）
- 试图让 Laravel 同时跑在 FPM 和 Swoole 上 → Hyperf 官方不兼容，社区方案（如 laravels）维护成本高、协程安全难保障，生产环境慎选
推荐路径：用 Composer 初始化标准 Hyperf 项目
Hyperf 是目前最成熟、文档最全、生态最活跃的 Swoole 应用框架，适合绝大多数需要高性能的场景。
终端执行：
立即学习“PHP免费学习笔记（深入）”；
composer create-project hyperf/hyperf-skeleton my-api进入目录后，它已自带：
- Swoole 扩展依赖检查与提示
- 基于协程的 HTTP 服务器、WebSocket 服务、RPC 服务模板
- 依赖注入容器、AOP、配置中心、数据库 ORM（hyperf/database）、Redis 客户端等开箱即用组件
启动命令：
php bin/hyperf.php start默认监听 0.0.0.0:9501，无需 Nginx/Apache（可前置反代做负载或 HTTPS 终止）。
在旧项目中谨慎复用 Swoole 原生能力（仅限 CLI 场景）
如果必须保留在原有框架中使用 Swoole 特性（例如异步发邮件、批量处理队列），请确保：
- 只在 CLI 命令中启用（如 php artisan swoole:task），绝不用于 Web 请求生命周期
- 显式开启协程 Hook：Swoole\Runtime::enableCoroutine(true);
- 替换所有同步 IO 调用：用 co\mysql 替代 mysqli，co\curl 替代 curl_exec，co\redis 替代 phpredis
- 避免全局变量、静态属性跨协程污染；DB 连接、Redis 实例需按协程 ID 隔离或使用连接池
避坑要点：常见错误与验证方式
集成后务必验证是否真正进入协程模式：
- 运行 php --ri swoole 确认扩展已加载且版本 ≥ 4.8（Hyperf v3.x 推荐 ≥ 5.0）
- 在代码中打印 Co::getCid()，Web 请求中应返回非 -1 的数字（表示当前在协程内）
- 禁用所有未 Hook 的同步函数（如 sleep()、file_get_contents()），否则会阻塞整个进程
- Hyperf 默认关闭 PHP 错误报告到页面，日志统一写入 runtime/logs/，别依赖 var_dump 调试
基本上就这些。不复杂但容易忽略细节——核心是接受“Swoole 不是插件，而是一套新运行范式”。
