CLI模式下Xdebug不触发的常见原因是PHP CLI未加载Xdebug扩展或xdebug.mode未设为debug；需确认CLI专属php.ini路径、启用xdebug.mode=debug、设置xdebug.start_with_request=yes，并匹配IDE监听端口与pathMappings。
CLI模式下Xdebug不触发的常见原因
PHP CLI默认不加载Xdebug扩展，即使phpinfo()里能看到它，也不代表CLI环境已启用。最常踩的坑是只配置了Apache/Nginx的php.ini，而忽略了php -i | grep "Loaded Configuration File"查到的CLI专属配置路径。
确认方式：运行php -m | grep xdebug，无输出即未加载；有输出但调试不生效，大概率是xdebug.mode没设对。
- 必须在CLI用的
php.ini中显式设置xdebug.mode=debug（PHP 8.0+）或xdebug.remote_enable=1（旧版） - 旧版Xdebug（2.x）需配
xdebug.remote_host和xdebug.remote_port；新版（3.x）改用xdebug.client_host和xdebug.client_port - CLI脚本不走HTTP请求，所以
XDEBUG_SESSION_START这类GET参数完全无效
启动调试会话的两种可靠方式
CLI没有浏览器那种“点击触发调试”的机制，得靠环境变量或命令行参数主动拉起调试连接。
- 方式一：用
XDEBUG_CONFIG环境变量指定IDE key + 其他参数，例如XDEBUG_CONFIG="idekey=PHPSTORM" php script.php - 方式二：直接传
-d参数覆盖配置，例如php -d xdebug.mode=debug -d xdebug.start_with_request=yes script.php -
xdebug.start_with_request=yes是关键开关，它让Xdebug在脚本启动时立刻尝试连IDE；设为default或no则不会自动触发 - 如果IDE监听端口不是9003（Xdebug 3默认），记得同步改
xdebug.client_port
VS Code / PHPStorm里必须检查的三项配置
IDE侧配置错一个，CLI调试就卡在“等待连接”状态，且无明显报错。
立即学习“PHP免费学习笔记（深入）”；
- PHPStorm：Settings → PHP → Debug → Xdebug → Debug port 必须与
xdebug.client_port一致（默认9003）；勾选Force break at first line when no path mapping specified可快速验证是否连通 - VS Code：
launch.json中port字段要匹配，且pathMappings必须精确映射本地路径到CLI执行时的绝对路径，例如"${workspaceFolder}": "/var/www/html"（注意CLI里__DIR__返回的是绝对路径） - 两者都需确保“Start Listening for Xdebug”按钮已点亮（PHPStorm叫“Start Listening for PHP Debug Connections”）
调试单脚本时最容易被忽略的陷阱
单脚本看似简单，但Xdebug的生命周期和路径解析逻辑会让调试中途断开或跳过断点。
- 脚本里如果有
exit()、die()或未捕获异常，Xdebug可能来不及上报完成状态，导致IDE显示“connection closed” - 使用
php -f script.php或./script.php（带shebang）时，工作目录可能影响pathMappings匹配，建议统一用php /full/path/to/script.php - Xdebug 3.1+ 默认开启
xdebug.log，临时加-d xdebug.log=/tmp/xdebug.log能直接看到连接失败原因，比如Failed to connect to client通常意味着IDE没在监听或防火墙拦截
路径映射不对和start_with_request没开，这两项占了实际调试失败的八成以上。
