直接运行php -m | grep xdebug，有输出说明已加载；否则需用php --ini和php -i | grep "Loaded Configuration File"确认当前生效的php.ini路径，并确保配置含xdebug.mode=debug、xdebug.client_host=127.0.0.1、xdebug.client_port=9003及绝对路径zend_extension。
phpEnv 里怎么确认 Xdebug 已加载
直接运行 php -m | grep xdebug，有输出就说明扩展已载入；没输出，说明没装对或没启用。常见原因是 phpEnv 切换 PHP 版本后，php.ini 路径变了，但你改的还是旧版本的配置文件。用 php --ini 查当前生效的 ini 文件路径，再用 php -i | grep "Loaded Configuration File" 双重确认。
phpEnv 下 Xdebug 配置必须改哪几项
新版 Xdebug（3.0+）不认 xdebug.remote_* 这类旧参数，硬写会静默失效。必须用以下三项：
-
xdebug.mode=debug—— 启用调试模式（不是develop或profile） -
xdebug.client_host=127.0.0.1—— phpEnv 默认走本地回环，别写成localhost（某些系统解析慢或失败） -
xdebug.client_port=9003—— 和 IDE 监听端口严格一致，不能是 9000（旧版默认）或 9001（部分教程误传）
另外，xdebug.start_with_request=yes 比 xdebug.idekey 更可靠，避免浏览器插件漏触发；zend_extension 的路径必须是绝对路径，比如 /Users/xxx/.phpenv/versions/8.1.22/lib/php/extensions/no-debug-non-zts-20210902/xdebug.so，不能用相对路径或环境变量。
VS Code 断点不命中？检查 launch.json 的 pathMappings
phpEnv 环境下，PHP 脚本在命令行或 Web Server 中运行时看到的文件路径，和 VS Code 工作区路径往往不一致。比如你的项目在 /Users/me/project，但 Apache DocumentRoot 是 /var/www/html，那么 pathMappings 必须显式映射：
立即学习“PHP免费学习笔记（深入）”；
{
"name": "Listen for Xdebug",
"type": "php",
"request": "launch",
"port": 9003,
"pathMappings": {
"/var/www/html": "${workspaceFolder}"
}
}
如果用的是 phpEnv 自带的内置服务器（php -S），路径通常就是 ${workspaceFolder}，但依然要写进 pathMappings，空对象或缺失字段会导致断点完全无效。
CLI 脚本调试失败的典型原因
用 php script.php 命令跑脚本时，Xdebug 默认不启动。必须加环境变量或参数：
- 临时启用：
XDEBUG_CONFIG="client_port=9003" php script.php - 或加参数：
php -dxdebug.mode=debug -dxdebug.client_host=127.0.0.1 script.php
注意：CLI 模式下 xdebug.start_with_request 不起作用；也不依赖浏览器插件。IDE 必须处于“监听”状态，且终端执行命令时不能在另一个网络命名空间（如 Docker 容器内直接跑 phpEnv 的 CLI，host 网络不通）。
最容易被忽略的是 phpEnv 多版本共存带来的配置错位——改了 8.1 的 php.ini，实际运行的是 8.2；或者 php -v 和 phpinfo() 显示的版本不一致。每次调不通，先跑一遍 which php 和 php -r "echo ini_get('xdebug.mode');" 确认执行链真实生效的位置。
