Workerman CLI 下 Xdebug 不触发需确认三点：一是 CLI 独立于 Web SAPI，须配置 CLI 专属 php.ini 并启用 xdebug.mode=debug；二是远程调试需确保 xdebug.client_host 可达且端口通，必要时用 frp 反向代理；三是 PHPStorm 路径映射必须严格匹配 FILE 输出的绝对路径。
Workerman CLI 模式下 Xdebug 不触发？先确认启动方式和环境隔离
Workerman 的 bin/start.php（或你自定义的 CLI 入口）是通过 PHP 命令直接运行的，它**不走 Web SAPI（如 fpm/apache）**，因此 Xdebug 配置必须适配 CLI 环境 —— 这意味着：Web 端调试成功的 xdebug.start_with_request = trigger 或浏览器插件完全无效；php-fpm 的 php.ini 也管不到 CLI。
实操建议：
- 用
php -i | grep "Loaded Configuration File"查 CLI 实际加载的 php.ini 路径，别改错文件 - CLI 下必须显式启用调试会话，Xdebug 3 推荐用环境变量：
XDEBUG_CONFIG="idekey=PHPSTORM"+export XDEBUG_SESSION=1（值需与 IDE key 一致） - Workerman 启动时若加了
-d参数（如php -d display_errors=1 start.php start -d），它会覆盖 php.ini 中的扩展加载，确保-d zend_extension=...显式传入（或改用php -c /path/to/cli.ini指定配置）
远程 CLI 调试连不上？重点检查 client_host 和端口穿透链路
Workerman 运行在远程服务器（比如 192.168.2.222），你的 PHPStorm 在本地（192.168.2.100），Xdebug 默认尝试反向连接 xdebug.client_host —— 但这个 IP 必须能被远程服务器直连。如果本地是 NAT 网络、公司防火墙限制、或使用了 frp 中转，直接填 127.0.0.1 或本地局域网 IP 就会失败。
实操建议：
- 远程服务器上运行
telnet 192.168.2.100 9001（端口需与xdebug.client_port一致），不通就说明网络层阻断 - 若本地无公网 IP，必须用 frp 反向代理：frpc 配置中
local_port = 9001对应 PHPStorm 监听端口，remote_port = 9001是 frps 开放给远程服务器连接的端口；远程服务器的xdebug.client_host改为 frps 的公网 IP（如124.221.77.32） - 别漏掉防火墙：远程服务器要允许出站到 frps IP:port；frps 服务器要开放
remote_port入站；本地 frpc 所在机器防火墙要放行本地9001
PHPStorm 配置 CLI Debug 时映射失败？路径同步必须严格一对一
Workerman CLI 脚本常含相对路径加载、动态 require、或基于 __DIR__ 定位文件，一旦 PHPStorm 里「本地路径 ↔ 远程路径」映射有偏差（比如少一个 /var/www/，或多一个 src/），断点就永远打不进真实执行的文件里 —— 表现为：控制台输出正常，IDE 却不中断，甚至提示 “No debug session”。
实操建议：
- 在 CLI 脚本开头加一行
var_dump(__FILE__); die;，运行后看输出的绝对路径，这就是远程真实路径，务必一字不差填入 PHPStorm 的 «Remote path» - PHPStorm 的 «Local path» 必须是你当前打开项目的根目录（不是子目录），且不能带尾部斜杠
- Workerman 使用多进程时（如
Worker::setDaemon(true)），Xdebug 只能在主进程生效；调试前先关掉 daemon 模式（删掉-d或设setDaemon(false)），否则子进程无法连接 IDE
Xdebug 3 模式配置写错？xdebug.mode 和 xdebug.start_with_request 是关键分水岭
Xdebug 2 的 xdebug.remote_enable 在 Xdebug 3 中已废弃，强行保留会导致 php -v 报错或静默失效；而 Workerman CLI 场景下，xdebug.start_with_request = yes 会强制每次 CLI 执行都尝试连接，但若 IDE 未监听，就会卡住几秒甚至超时失败 —— 这和 Web 请求可异步重试完全不同。
实操建议：
- CLI 调试推荐用
xdebug.start_with_request = trigger+ 环境变量组合，更可控：XDEBUG_SESSION=PHPSTORM php start.php start - 必须设置
xdebug.mode=debug（不是develop或空值），否则即使连接成功也不会进入调试流程 -
xdebug.client_host别用localhost：它在远程服务器上解析为 127.0.0.1，不是你的开发机；填具体 IP 或 DNS 名（确保远程服务器能解析）
