Xdebug3 命令行 (CLI/artisan) vs HTTP 网页模式

Xdebug3 命令行 (CLI/artisan) vs HTTP 网页模式 差异总结（WSL2 + Laravel 场景）

共用配置（HTTP 和 CLI 相同，写在 php.ini）

[xdebug]
zend_extension=xdebug.so
xdebug.mode=debug,develop
xdebug.start_with_request=trigger
xdebug.client_port=9003
xdebug.idekey=PHPSTORM
xdebug.log=/tmp/xdebug.log
xdebug.log_level=7

共用部分：端口、idekey、mode、trigger 模式、日志。

HTTP 模式额外配置（网页调试）

1. xdebug.discover_client_host=On（推荐开启，网页自动发现客户端 IP）
2. 浏览器安装 Xdebug Helper，点击开启调试（自动设置 Cookie XDEBUG_TRIGGER=1）
3. PHPStorm 配置 Server + Path mapping，不需要 PHP_IDE_CONFIG
4. 访问网页：http://xxx?XDEBUG_TRIGGER=1 或者插件打开触发器，触发调试

网页模式优势：不需要改任何环境变量，插件一键开关调试。

CLI（artisan）额外配置

不能依赖 HTTP 相关能力，全部靠环境变量注入

WIN_HOST=$(ip route | grep default | awk '{print $3}')
export XDEBUG_TRIGGER=1
export XDEBUG_CONFIG="client_host=${WIN_HOST} client_port=9003 idekey=PHPSTORM discover_client_host=0 connect_timeout_ms=2000"
export PHP_IDE_CONFIG="serverName=wsl-laravel"
php artisan app:test

关键要点：

1. discover_client_host=0：关闭 HTTP 头自动发现（CLI 无 http 头，无用还会产生多余日志）
2. client_host：指向Windows 宿主机网关 IP（ip route default gw），新版 WSL 不能使用 resolv.conf 里的 DNS 代理 IP
3. PHP_IDE_CONFIG：CLI 独有，告诉 PHPStorm 使用哪个 Server 的路径映射，解决找不到文件报错
4. 触发器：只能用环境变量XDEBUG_TRIGGER=1，Cookie 无效

常见踩坑差异

1. WSL 场景：
   • HTTP：discover_client_host=on 能拿到浏览器 Windows IP，自动连接 IDE
   • CLI：discover_client_host 无效，必须手动指定 client_host 为 Windows 网关 IP
2. 路径映射：
   • HTTP：很多时候不填 PHP_IDE_CONFIG 也能正常识别
   • CLI：缺少 PHP_IDE_CONFIG，PHPStorm 一定会报找不到文件
3. queue:work 特殊坑（CLI 独有）
   • art-debug queue:work 启动后，进程常驻。断点只在任务开始时触发一次；修改断点代码，必须重启 queue 进程。网页没有常驻进程问题。

推荐完整最佳实践

[xdebug]
zend_extension=xdebug.so
xdebug.mode=debug,develop
xdebug.start_with_request=trigger
xdebug.client_port=9003
xdebug.idekey=PHPSTORM
xdebug.log=/tmp/xdebug.log
xdebug.log_level=7
xdebug.discover_client_host=On ; 网页需要，CLI时环境变量会临时关闭它

CLI 调试时，环境变量 discover_client_host=0 会临时覆盖 ini 里的 On，互不冲突。

快捷方式 - alias

alias art-debug='WIN_HOST=$(ip route | grep default | awk "{print \$3}"); XDEBUG_MODE=debug,develop XDEBUG_CONFIG="client_host=${WIN_HOST} client_port=9003 idekey=PHPSTORM discover_client_host=0 connect_timeout_ms=2000" XDEBUG_TRIGGER=1 PHP_IDE_CONFIG="serverName=wsl-laravel" php artisan'