PhpStorm调试Hyperf协程框架的详细配置指南-phpstorm-PHP中文网

hyperf调试断点失效主因是热更新干扰，需停server:watch、禁file watcher、设daemonize=false、用php -e启动；yasd需配remote_host和php_ide_config；代理类路径须映射；协程调试须打coroutine_id日志。

phpstorm调试hyperf协程框架的详细配置指南

Hyperf 的 server:watch 和 File Watcher 触发的 reload.sh 都会频繁 fork 新进程、重载 Swoole Server，导致 Xdebug/Yasd 的调试连接被中断或复用失败。断点不触发，90% 是因为你在 debug 模式下还开着热更新。

实操建议：

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

Yasd 是目前 Hyperf + Swoole 场景下最稳定的调试扩展，但它不像 Xdebug 那样自动探测 IDE，必须显式告知目标地址和服务器名。

常见错误现象：PhpStorm 显示 “Waiting for connection”，但请求发出后无响应；php --ri yasd 显示 debug_mode => remote 却没日志输出。

实操建议：

yasd.remote_host 必须填宿主机可路由的 IP：WSL2 填 172.28.0.1（不是 127.0.0.1），Docker 填宿主机网关，Mac 直接填 127.0.0.1
Linux/WSL 环境下必须设置环境变量：export PHP_IDE_CONFIG="serverName=hyperf-local"（serverName 要和 PhpStorm → Settings → PHP → Servers 里配的名字完全一致）
确认 php.ini 中只启用了 yasd.so，注释掉所有 xdebug 或 sdebug 行，二者互斥
用 netstat -tuln | grep 9000 验证端口是否被占用，PhpStorm 的 Debug 面板需处于 “Start Listening” 状态

Hyperf 启动时会自动生成代理类（如 App\Controller\IndexControllerProxy），实际执行的是代理类而非原始文件。PhpStorm 按你编辑的源码路径下断点，但运行时代码已切换到代理类，路径不匹配自然跳过。

实操建议：

打开 PhpStorm → Settings → Languages & Frameworks → PHP → Servers，新增或编辑对应 server，勾选 “Use path mappings”，添加映射：
Local path: $ProjectFileDir$ （或你的项目绝对路径）
Remote path: /var/www/html（Docker）、/home/user/project（WSL）或实际运行时的工作目录
生成代理类后，可在 runtime/container/proxy/ 下找到对应 *Proxy.php 文件，直接在该文件里手动加断点验证是否生效
开发期可临时关闭代理生成（不推荐长期用）：config/autoload/aspect.php 中设 'enable' => false

协程调试最难的不是断点，而是“不知道当前执行的是哪个协程”。一个请求可能 spawn 出 5 个子协程，日志混在一起，var_dump 输出无法归属，Xdebug 又只停在当前协程上下文，容易误判阻塞点。

实操建议：

所有日志调用前加协程 ID：$this->logger->info('user fetch', ['coroutine_id' => \Hyperf\Coroutine::id()]);
Hyperf 默认日志已注入 coroutine_id 和 request_id，只需确保 config/autoload/logger.php 中 formatter 使用 Hyperf\Logger\Formatter\LineFormatter，且 include_stacktrace 设为 false（避免协程堆栈污染）
排查阻塞时优先用 \Swoole\Coroutine::stats() 查看当前协程数、调度延迟，比盲打断点更高效
别依赖 IDE 的“Variables”面板看全局状态——协程间内存隔离，它只反映当前协程栈帧，跨协程变量得靠日志或 runtime 目录下的缓存文件人工比对