workerman cli 模式下 xdebug 不触发，因 cli 独立于 web sapi，须配置专属 php.ini 并启用 xdebug.mode=debug；远程调试需确保 xdebug.client_host 可达且端口通，phpstorm 路径映射必须严格匹配 file 输出的绝对路径。
Workerman CLI 模式下 Xdebug 不触发？先确认 CLI 独立配置
Workerman 启动脚本（如 start.php）是通过 php 命令直接运行的，完全绕过 Web SAPI（如 fpm 或 Apache），所以 Web 环境里配好的 xdebug.start_with_request=trigger 或浏览器插件毫无作用。
实操建议：
- 用
php -i | grep "Loaded Configuration File"查 CLI 实际加载的php.ini路径，别改错文件 - Xdebug 3 必须显式启用调试会话：
XDEBUG_CONFIG="idekey=PHPSTORM"+export XDEBUG_SESSION=1（值需与 PHPStorm 的ide key一致） - 若启动时用了
-d参数（如php -d display_errors=1 start.php start -d），它会覆盖php.ini中的扩展加载，确保-d zend_extension=/path/to/xdebug.so显式传入
Swoole 协程中 Xdebug 断点失效？不是不能用，是默认会卡死
Swoole 的协程模型和 Xdebug 的同步阻塞调试机制天然冲突：Xdebug 遇到断点就挂起整个 Worker 进程，所有协程一起冻结，I/O 停摆，连接超时，甚至触发 Segmentation Fault。
常见错误现象：
- 调试时服务无响应、HTTP 请求超时、WebSocket 连接断开
- PHPStorm 显示“Connected”，但断点不命中，或命中后无法继续执行
- 日志里出现
zend_mm_heap corrupted或Segmentation fault
可行方案（仅限开发环境）：
Swoole 6.1.1 是一个专为 PHP 设计的高性能事件驱动并发网络引擎。作为稳定版，它修复了编译时对 zlib 依赖的缺失及 curl 模块的内存安全风险。该版本支持协程、多线程与多进程架构，内置 TCP/HTTP/WebSocket 服务器，能够显著提升 PHP 在微服务、实时通信等场景下的执行效率与并发能力。
- 禁用协程：启动时加
--disable-coroutine（Swoole 5.0+）或改用SWOOLE_BASE模式，让代码退化为同步风格再调试 - 只对非协程路径启用 Xdebug：用
xdebug.mode=debug+xdebug.start_with_request=no，再通过环境变量临时开启，例如XDEBUG_MODE=debug php index.php - 避免在
go()内部设断点；把待调试逻辑抽成普通函数，在协程外调用并打断点
远程调试连不上 9003 端口？网络链路比配置更重要
Workerman/Swoole 运行在远程服务器（如 192.168.2.222），PHPStorm 在本地（192.168.2.100），Xdebug 默认尝试反向连接 xdebug.client_host —— 但这个 IP 必须能被远程服务器直连。NAT、防火墙、Docker 网络、WSL2 子系统都会切断链路。
实操建议：
- 远程服务器上执行
telnet 192.168.2.100 9003（端口需与xdebug.client_port一致），不通就说明网络层已阻断 - 本地无公网 IP 时，必须用 frp 反向代理：
frpc的local_port = 9003对应 PHPStorm 监听端口，remote_port = 9003是 frps 开放给远程服务器连接的端口；远程服务器的xdebug.client_host改为 frps 的公网 IP - 检查三处防火墙：远程服务器出站、frps 入站、本地 frpc 所在机器入站（9003）
PHPStorm 路径映射失败？FILE 输出的绝对路径必须一字不差
Workerman CLI 脚本常含 __DIR__、相对 require、动态加载等操作，一旦 PHPStorm 的「本地路径 ↔ 远程路径」映射有偏差（比如少一个 /var/www/，或多一个 src/），断点就永远打不进真实执行的文件里 —— 表现为控制台输出正常，IDE 却不中断。
验证方法：
- 在入口脚本第一行加
var_dump(__FILE__); die;，看输出的绝对路径是什么 - PHPStorm 中打开
Preferences > PHP > Servers，核对 “Absolute path on the server” 是否与__FILE__完全一致（包括大小写、末尾斜杠、符号链接展开状态） - 如果 Workerman 运行在 Docker 或 WSL2，路径可能经过多层映射，优先以容器内
pwd和readlink -f结果为准
复杂点在于：Swoole 的协程切换会让 __FILE__ 和实际执行位置产生歧义，而 Workerman 的回调函数又常通过字符串路径动态加载 —— 这时候光靠 IDE 自动映射不够，得手动补全每一层 require 的路径映射。
