Hyperf调试断点失效主因是热更新干扰，需停server:watch、禁File Watcher、设daemonize=false、用php -e启动；Yasd需配remote_host和PHP_IDE_CONFIG；代理类路径须映射；协程调试须打coroutine_id日志。
php bin/hyperf.php start 无法进断点？先关 server:watch 和热更新
Hyperf 的 server:watch 和 File Watcher 触发的 reload.sh 都会频繁 fork 新进程、重载 Swoole Server，导致 Xdebug/Yasd 的调试连接被中断或复用失败。断点不触发，90% 是因为你在 debug 模式下还开着热更新。
实操建议：
- 停掉所有
server:watch进程：pkill -f "php.*server:watch" - 禁用 PhpStorm 的 File Watcher（尤其勾选了 “Auto-save edited files to trigger watcher” 的）
- 确认
config/autoload/server.php中'daemonize' => false（调试时必须前台运行） - 启动命令统一改用：
php -e bin/hyperf.php start（-e是关键，启用 Zend 引擎调试支持）
Yasd 配置后仍连不上 PhpStorm？检查 remote_host 和 PHP_IDE_CONFIG
Yasd 是目前 Hyperf + Swoole 场景下最稳定的调试扩展，但它不像 Xdebug 那样自动探测 IDE，必须显式告知目标地址和服务器名。
常见错误现象：PhpStorm 显示 “Waiting for connection”，但请求发出后无响应；php --ri yasd 显示 debug_mode => remote 却没日志输出。
立即学习“PHP免费学习笔记（深入）”；
实操建议：
-
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” 状态
断点打在 Controller 却不命中？代理类路径映射没配对
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
协程内变量看不到、堆栈混乱？日志必须带 coroutine_id
协程调试最难的不是断点，而是“不知道当前执行的是哪个协程”。一个请求可能 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目录下的缓存文件人工比对
真正卡住人的从来不是配置步骤，而是协程调试本身没有“单线程时间轴”这个前提。每个断点都只属于某个瞬间的某个协程，漏掉一次 go() 或 defer，上下文就彻底断裂。动手前，先想清楚你要调试的到底是“这行代码是否执行”，还是“这个协程为什么没结束”。
