VSCode中PHP-Debug插件配置与Xdebug调试步骤-VSCode-PHP中文网

vscode中php断点不触发主因是xdebug.mode=debug未生效、xdebug.client_port与vscode监听端口9003不一致，或launch.json缺失有效监听配置及pathmappings路径映射错误。

vscode中php-debug插件配置与xdebug调试步骤

VSCode 中 PHP Debug 插件无法触发断点，90% 是因为 xdebug.mode=debug 没生效、xdebug.client_port 与 VSCode 监听端口不一致，或 launch.json 缺失有效监听配置 —— 不是插件装错了，而是通信链路在某一处断了。

PHP 8.5.5 环境下必须使用 Xdebug 3.3+（Xdebug 4 尚未正式发布），旧版 Xdebug 2 的 xdebug.remote_enable 配置会直接导致静默失败。

执行 php -v 确认输出含 with Xdebug 字样；若无，说明扩展未启用
执行 php --ri xdebug 查看 Version 和 Supports phpinfo() 字段，确保不是 disabled
执行 php --ini 找到真实生效的 php.ini 路径，打开后检查 zend_extension 行是否指向存在的 .so 文件（如 /usr/local/lib/php/pecl/20230831/xdebug.so）
若用 Docker，php -m | grep xdebug 必须在容器内执行，宿主机查不到

Xdebug 3 默认关闭远程调试，只靠 zend_extension 加载远远不够。漏掉任意一项都会让 VSCode 收不到连接请求。

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

xdebug.mode=debug：唯一启用调试模式的方式，xdebug.remote_enable=1 已被废弃
xdebug.start_with_request=trigger：避免全站请求都连调试器；设为 yes 可省去 URL 参数，但开发环境慎用
xdebug.client_host=127.0.0.1：本地调试写死此值；Docker 容器中需改为 host.docker.internal（macOS/Windows）或宿主机网关 IP（Linux）
xdebug.client_port=9003：Xdebug 3 默认端口，9000 是 Xdebug 2 的，混用必报 Connection refused
务必删除所有 xdebug.remote_* 开头的旧参数，它们会覆盖新配置

launch.json 不是“生成完就完事”，它要和 Xdebug 的行为严格对齐，否则 VSCode 在监听，Xdebug 却往别处发包。

模板选 Listen for Xdebug，不是 Launch Built-in Web Server（后者不走 DBGp 协议）
"port": 9003 必须与 php.ini 中 xdebug.client_port 完全一致
"pathMappings" 是路径映射关键项：若 PHP 运行在 /var/www/html，而你本地项目在 /Users/me/project，就得写 "/var/www/html": "${workspaceFolder}"
如果用 Laravel Homestead/Valet/Docker，pathMappings 错误会导致断点灰色不可用（VSCode 找不到对应文件）

URL 参数最常用，但 REST API 或 CLI 脚本场景下容易失效；xdebug_break() 是兜底手段，但仅限 CLI 或已知入口脚本。

Web 请求：在 URL 后加 ?XDEBUG_SESSION_START=VSCODE（idekey 值必须匹配 php.ini 中的 xdebug.idekey）
CLI 脚本：终端执行前加环境变量 XDEBUG_CONFIG="idekey=VSCODE" php script.php
硬编码断点：在 PHP 代码中插入 xdebug_break();，VSCode 会立即捕获（无需 URL 参数）
浏览器插件（如 Xdebug Helper）可一键切换开关，但依赖 Cookie，跨域或 API 请求时不可靠

最容易被忽略的是 xdebug.log —— 建议始终开启：xdebug.log=/tmp/xdebug.log，权限设为 644，连接失败时第一手日志比猜配置快十倍；另外，PHP-FPM 或 Apache 修改 php.ini 后必须重启对应进程，仅重启 VSCode 没用。