Xdebug 3 调试失败主因是配置链松动，需严格配置三行：xdebug.mode=debug、xdebug.start_with_request=trigger、xdebug.client_host；路径映射、触发方式和 CLI 调试须按规范处理。
Xdebug 不是“学完就能用”，而是配错一行就断点不命中、连不上、没日志——核心问题从来不是功能多，而是配置链上哪一环松动了。
php.ini 里只留这三行 Xdebug 3 必需配置
Xdebug 3 把旧版一堆 remote_* 配置全废弃了，硬加进去反而报 Unknown configuration setting。删干净后，只保留：
-
xdebug.mode=debug：不设这行，zend_extension加载成功也等于没开调试 -
xdebug.start_with_request=trigger：设成yes会每请求都连 IDE，但 IDE 没监听时 Xdebug 默默超时放弃，不报错也不提示，极难排查 -
xdebug.client_host=127.0.0.1（本地）或host.docker.internal（Docker 容器内连宿主机）：写localhost在容器里会连自己，必失败
端口默认是 9003，不是旧版的 9000；改了 xdebug.client_port 就必须同步改 IDE 的监听端口，否则连接被拒绝。
VS Code 断点灰色？检查 launch.json 里的 pathMappings
断点变灰色、点击无效，90% 是路径映射没对上。PHP 进程里文件路径（比如 /var/www/html/index.php）和你本地项目路径（比如 /Users/you/project）必须一对一映射，少一个斜杠或大小写错都会失灵。
立即学习“PHP免费学习笔记（深入）”；
示例配置（注意路径必须是绝对路径）：
{
"version": "0.2.0",
"configurations": [
{
"name": "Listen for Xdebug",
"type": "php",
"request": "launch",
"port": 9003,
"pathMappings": {
"/var/www/html": "${workspaceFolder}"
}
}
]
}查 PHP 实际运行路径：在脚本里加 echo __FILE__;，再和 pathMappings 左边键比对。
浏览器访问不触发断点？别信“自动监听”，要显式传参或装插件
Xdebug 3 不再默认监听所有请求。不带触发信号，它根本不会尝试连 IDE。
- 最稳方式：URL 后加
?XDEBUG_SESSION_START=PHPSTORM（值可以任意，但推荐用 IDE 默认 key，避免兼容问题） - 省事方式：装官方
Xdebug Helper浏览器插件（Chrome/Firefox），点图标激活，它自动设 cookieXDEBUG_SESSION=PHPSTORM - 别用
?xdebug_session_start=1小写——Xdebug 对参数名大小写敏感，小写不识别
如果用了 Docker，且 PHP 在容器里、IDE 在宿主机，XDEBUG_SESSION_START 有效，但 Xdebug Helper 插件可能因跨域或 cookie 路径失效，此时 URL 参数更可靠。
CLI 脚本调试失败？xdebug_break() 是兜底方案
命令行跑 PHP 脚本时，XDEBUG_SESSION_START 参数没法塞进 URL，环境变量 XDEBUG_TRIGGER=1 又依赖 IDE 正在监听——任一环节断掉，调试就卡住。
这时候直接在代码里插一句：
if (PHP_SAPI === 'cli') {
xdebug_break();
}xdebug_break() 不依赖外部触发，只要 Xdebug 扩展加载且 xdebug.mode=debug，执行到这行就强制暂停，IDE 能立刻接管。适合临时定位 CLI 脚本逻辑、队列任务、定时任务等场景。
注意：xdebug_break() 是函数调用，不是关键字；忘加括号或拼错成 xdebug_break 会导致 Fatal error，但不会静默失败——这点比配置项友好得多。
