CLI模式下Xdebug不生效的常见原因是CLI与Web使用不同php.ini，Xdebug未在CLI配置中加载；Xdebug 3需显式设置xdebug.mode=debug且依赖环境变量或-d参数启动会话，而非Web端触发方式。
CLI模式下Xdebug不生效的常见原因
Xdebug在CLI下默认可能完全不加载，最直接的表现是运行php -v看不到Xdebug扩展信息，或者php --ini显示的配置文件里没加载xdebug.ini。根本原因通常是CLI和Web服务器（如Apache/Nginx）使用了不同的php.ini路径，而Xdebug只配在了Web用的配置里。
- 检查当前CLI使用的配置：
php --ini，重点关注“Loaded Configuration File”那一行 - 运行
php -m | grep xdebug，返回空说明扩展根本没加载 - Xdebug 3+要求显式启用，仅加载扩展不够，必须设置
xdebug.mode=debug或xdebug.mode=develop - CLI下不会自动读取
.htaccess或Web服务器的环境变量，所有配置必须落在INI文件中或通过-d参数传入
让Xdebug在CLI中真正启动调试会话
CLI脚本要触发Xdebug连接IDE（如PhpStorm、VS Code），不能依赖浏览器插件或GET参数，必须靠环境变量或命令行参数主动开启调试会话。
- 最可靠方式：启动时加
-d xdebug.mode=debug -d xdebug.start_with_request=yes
示例：php -d xdebug.mode=debug -d xdebug.start_with_request=yes script.php - 或者设环境变量（推荐用于反复调试）：
XDEBUG_MODE=debug php script.php - 注意
xdebug.client_host默认是127.0.0.1，如果IDE在Docker或WSL里，需改成对应宿主机IP（如host.docker.internal或真实局域网IP） -
xdebug.client_port默认是9003，确保IDE监听端口与之匹配，且防火墙/SELinux未拦截
PHP版本与Xdebug 3配置项的对应关系
Xdebug 3彻底重构了配置命名，老项目从Xdebug 2升级后，xdebug.remote_enable这类参数全失效，继续保留会导致PHP启动报错或静默忽略。
-
xdebug.remote_enable→ 改为xdebug.mode=debug（或develop、profile等组合） -
xdebug.remote_host→ 改为xdebug.client_host -
xdebug.remote_port→ 改为xdebug.client_port -
xdebug.remote_autostart→ 改为xdebug.start_with_request=yes -
xdebug.idekey已废弃，IDE靠xdebug.client_host和端口识别，无需设置
调试时断点不命中或连接超时的实际处理步骤
现象是脚本跑完也没停在断点，控制台无错误但IDE右下角显示“Waiting for connection”，本质是Xdebug发出了请求，但没被IDE收到。
立即学习“PHP免费学习笔记（深入）”；
- 先确认IDE是否已在监听：PhpStorm点“Run → Start Listening for PHP Debug Connections”，VS Code检查
launch.json里port是否为9003且request为launch - 在CLI命令后加
-d xdebug.log=/tmp/xdebug.log，查看日志里是否有Connecting to configured address或Connection refused - 如果日志出现
Failed to connect，大概率是xdebug.client_host填错了——比如在Mac上用Docker Desktop，应填host.docker.internal而非localhost - 避免同时开多个调试会话：Xdebug默认只连第一个响应的客户端，IDE切到后台或断开监听后，后续请求会被丢弃，需重启脚本
Xdebug CLI调试的复杂点不在配置本身，而在于环境隔离——PHP CLI、IDE、网络栈三者之间的连接路径必须全程可达，任意一环的IP/端口/防火墙/监听状态出问题，都会表现为“看起来配对了，但就是不中断”。
