VS Code配置Xdebug环境教程：PHP开发调试技巧详解-php教程-PHP中文网

vs code php断点不生效主因是xdebug.mode=debug未正确配置、xdebug.client_port与launch.json中port不一致、pathmappings映射错位；需用php --ini和php -m | grep xdebug确认cli加载的php.ini及xdebug启用状态，并严格按xdebug 3规范配置参数与路径映射。

vs code配置xdebug环境教程：php开发调试技巧详解

VS Code 调试 PHP 断点不生效，90% 是因为 xdebug.mode=debug 没写对、port 和 xdebug.client_port 不一致，或 pathMappings 映射完全错位——不是插件没装好，也不是 VS Code 有问题。

确认 Xdebug 是否真在 CLI 环境下启用

VS Code 调试依赖的是 PHP CLI（命令行）环境，不是 Apache/Nginx 加载的那个 php.ini。很多人改了 Apache 的配置，却忘了 CLI 根本不读它。

终端运行 php --ini，看 Loaded Configuration File 路径，记下来
运行 php -m | grep xdebug，有输出才说明 CLI 真加载了；没输出就白配
如果输出是 Xdebug v3.x，但 php.ini 里还写着 xdebug.remote_enable=1，PHP 启动会静默忽略甚至报错
Windows 用户特别注意：WAMP/XAMPP 通常有两套 php.ini（Apache 目录下 + PHP 目录下），CLI 用的是后者

php.ini 必须写的四条核心配置（Xdebug 3+）

Xdebug 3 彻底废弃了 remote_* 前缀，硬套旧教程只会让调试器连不上。以下字段缺一不可，且必须写在未注释的 [xdebug] 段内：

btpanel phpsite 宝塔面板PHP网站

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

下载

zend_extension=xdebug（Linux/macOS）或 zend_extension=php_xdebug.dll（Windows，路径要绝对且含引号，如 "C:/php/ext/php_xdebug.dll"）
xdebug.mode=debug（不是 on、不是 1，写错等于没开）
xdebug.client_port=9003（Xdebug 3 默认端口，不是 9000；改了就要同步改 VS Code）
xdebug.start_with_request=yes（自动触发，省去手动加 ?XDEBUG_SESSION_START=1；设为 trigger 就得靠浏览器插件或 URL 参数）
强烈建议加一行：xdebug.log=/tmp/xdebug.log（macOS/Linux）或 xdebug.log=C:/tmp/xdebug.log（Windows），出问题直接翻日志，比猜快十倍

launch.json 中 pathMappings 映射必须“左服务器右本地”

VS Code 收到的是 PHP 进程看到的文件路径（比如容器里是 /app/index.php），它得知道这个路径对应你本地哪一行代码。映射反了、漏了、斜杠方向错了，断点就显示空心圆，点开也无效。

本地开发（Apache DocumentRoot 是 C:/xampp/htdocs）： "pathMappings": { "C:/xampp/htdocs/": "${workspaceFolder}/" }（Windows 用正斜杠 /，不是 \）
Docker 容器中跑 PHP，项目挂载进容器 /var/www/html： "pathMappings": { "/var/www/html/": "${workspaceFolder}/" }
WSL2 下开发，PHP 在 WSL 里，路径是 /mnt/c/Users/name/project： "pathMappings": { "/mnt/c/Users/name/project/": "${workspaceFolder}/" }（不能写 C:\）
映射值末尾都带 /，两边严格一致；空值、{}、或只写 "${workspaceFolder}": "${workspaceFolder}" 都会失效

VS Code 启动监听后仍连不上？先盯住这三个点

点击 ▶️ 开始调试后，底部状态栏应显示 Listening on port 9003。如果访问页面没反应，别急着重装，先查：

终端再跑一次 php -v，确认输出含 with Xdebug 字样；没出现说明刚改的 php.ini 没被 CLI 加载（可能改错文件，或没重启终端）
检查防火墙是否拦截了 9003 端口（尤其是 Windows Defender 防火墙，有时会静默阻止）
macOS Monterey 及更新版本、Docker Desktop 默认网络下，xdebug.client_host 不能写 127.0.0.1，得换成宿主机网关，常见是 10.0.2.2 或 host.docker.internal
launch.json 里的 port 和 php.ini 的 xdebug.client_port 必须数字完全一致，多一个空格都不行