PHP断点调试必须安装Xdebug 3.0+或phpdbg，VSCode需通过PHP Debug扩展协作；常见失败原因包括版本错配、xdebug.mode=debug未设置、pathMappings路径映射错误、Xdebug会话未触发及PHP Debug扩展版本过低不兼容PHP 8.2+。
PHP断点调试必须装xdebug或phpdbg
VSCode本身不解析PHP，断点生效的前提是后端有调试代理。目前只有 xdebug（推荐 3.0+）和内置的 phpdbg 能与 VSCode 的 PHP Debug 扩展协作。装错版本（比如 xdebug 2.x 配置套用 3.x 文档）是断点不触发的最常见原因。
-
xdebug.mode=debug是 xdebug 3 的必需项，旧版的xdebug.remote_enable=1已失效 - 确认
php -v输出中含with Xdebug v3.x.x，而非仅显示loaded modules却无版本信息（说明未真正加载） - Windows 下注意
php.ini路径是否为 Apache/CLI 实际读取的那个——php --ini和phpinfo()显示的路径可能不同
launch.json里不能只写"port": 9003
VSCode 的 launch.json 必须匹配 xdebug 的实际监听行为。xdebug 3 默认使用 9003 端口，但若你改过 xdebug.client_port，这里就必须同步；更关键的是，漏掉 pathMappings 会导致断点“灰掉”——VSCode 找不到本地文件与远程执行路径的对应关系。
{
"version": "0.2.0",
"configurations": [
{
"name": "Listen for Xdebug",
"type": "php",
"request": "launch",
"port": 9003,
"pathMappings": {
"/var/www/html/": "${workspaceFolder}/"
},
"hostname": "localhost",
"runtimeExecutable": "/usr/bin/php"
}
]
}
- Linux/macOS 上
pathMappings的左侧是容器或服务器上的绝对路径（如 Docker 中的/var/www/html/），右侧是本地项目根目录 - Windows 用户若用 WSL2，左侧应填 WSL 内路径（如
/home/user/project/），不是C:\\... - 如果用 PHP 内置服务器（
php -S localhost:8000），需加"serverSourceRoot": "${workspaceFolder}"，否则断点无法映射
断点热更失败多数因为没关xdebug.start_with_request
所谓“热更”，是指修改代码后不重启 Web 服务就让新断点生效。这依赖 xdebug 是否在每次请求时重新建立连接。默认 xdebug.start_with_request = trigger（需浏览器插件或 ?XDEBUG_SESSION_START=1 触发），但如果设成 yes，则每个请求都强制调试，性能差且易冲突；设成 off 则断点完全不触发。
- 开发时建议保持
xdebug.start_with_request = trigger，用浏览器 Xdebug Helper 插件一键开启会话 - 修改 PHP 文件后，VSCode 不需要手动“重启调试”，只要下一次带调试会话的请求进来，新断点就会立即生效
- 如果改了
.php文件却仍停在旧位置，检查是否浏览器未发送XDEBUG_SESSIONcookie 或 GET 参数——可临时在 URL 加?XDEBUG_SESSION_START=1测试
PHP Debug扩展不兼容PHP 8.2+的某些错误捕获模式
PHP 8.2 引入了 throw new Error 类型，而老版本 PHP Debug 扩展（v1.20.0 之前）会因无法解析这类异常导致调试中断、断点失灵甚至 VSCode 卡死。这不是配置问题，是扩展本身缺陷。
立即学习“PHP免费学习笔记（深入）”；
- 务必升级到
PHP Debug扩展 v1.21.0 或更高版本（发布于 2023 年底） - 检查方法：在
launch.json中启用"log": true，查看输出面板里是否有Failed to handle error event类似日志 - 若用 Laravel Octane 或 Swoole，不要用
launch模式调试 HTTP 请求——它们复用进程，xdebug 连接易混乱；改用attach模式 +xdebug.start_upon_error=yes捕获特定异常更可靠
