断点不触发、变量undefined、空心圆，90%因pathmappings未配对或php cli加载了错误php.ini；须用php --ini确认实际路径，php -v验证xdebug是否启用，并严格区分xdebug 2/3配置（如xdebug.mode=debug vs xdebug.remote_enable=1）及端口（9003 vs 9000）。
断点不触发、变量显示 undefined、VSCode 显示空心圆——90% 是 pathMappings 没配对，或 PHP CLI 加载的 php.ini 根本不是你改的那个。
确认 PHP CLI 实际加载的 php.ini 路径
VSCode 调试依赖的是 PHP 命令行（CLI）环境，不是 Apache 或 Nginx 的配置。很多人改了 Apache 目录下的 php.ini，但 php -v 用的是另一个。
- 在终端运行
php --ini，看Loaded Configuration File那一行的路径 - 运行
php -v，确认输出里有with Xdebug字样；没有就说明这个php.ini没启用 Xdebug - Windows 用户：WAMP/XAMPP 通常有两套
php.ini（Apache 目录下 + PHP 安装目录下），CLI 用的是后者 - macOS/Linux 用户：Homebrew 安装的 PHP，路径通常是
/usr/local/etc/php/X.Y/php.ini，别去碰/etc/php.ini - 改完必须重启 VSCode 终端（或整个 VSCode），否则
php -v看不到变化
区分 Xdebug 2 和 Xdebug 3 的关键配置项
Xdebug 3 彻底废弃了 xdebug.remote_* 系列参数，写进去不仅无效，还可能让 PHP 启动失败或静默忽略。
- 先用
php -v | grep xdebug确认版本：Xdebug v3.x→ 用新参数；Xdebug v2.9→ 用旧参数（但建议升级） - Xdebug 3 必须写：
xdebug.mode=debug（不是on或1），xdebug.client_port=9003（默认不是 9000） - Xdebug 2 必须写：
xdebug.remote_enable=1，xdebug.remote_port=9000（注意端口差异） - 两者都需
zend_extension=xdebug（Linux/macOS）或zend_extension=php_xdebug.dll（Windows） - 混用配置（比如 Xdebug 3 里写
xdebug.remote_host）会导致调试连接完全静默失败
pathMappings 必须严格匹配服务器路径与本地路径
这是断点不生效的最高频原因。Xdebug 发送的是服务器上的绝对路径（比如 /var/www/html/index.php），VSCode 必须知道它对应你本地哪个文件夹。
-
pathMappings是必填项，空对象{}或漏写等于没配 - 格式必须是 POSIX 风格：用正斜杠
/，Windows 用户别写C:\project，要写/c/Users/me/project/（WSL）或/var/www/html/（Docker） - 左侧是服务器路径（容器内、远程机、本地 Apache DocumentRoot），右侧是
${workspaceFolder}或具体本地路径，顺序反了就找不到文件 - Docker 场景下，如果
docker run -v $(pwd):/app，那左边必须写/app，不是宿主机路径 - 配错的典型现象：断点能设上（实心圆），但命中后变量全为
undefined，或跳转到错误文件
浏览器请求必须带调试触发信号
VSCode 只监听，不主动发起连接。Xdebug 默认不开启调试会话，得靠请求携带标识来激活。
- 装官方
Xdebug Helper插件（Chrome/Firefox），右键图标选Debug（不是Profile） - 插件默认发
XDEBUG_SESSION_START=PHPSTORM，所以launch.json中的ideKey要保持默认，或显式写成"ideKey": "PHPSTORM" - 命令行测试时，手动加参数：
curl "http://localhost/test.php?XDEBUG_SESSION_START=PHPSTORM" - 若设了
xdebug.start_with_request=yes，每次请求都会尝试连接，适合 CLI 或简单 Web 场景；但线上环境务必设为trigger - 如果 VSCode 显示“正在等待 Xdebug 连接”却一直不动，先查
xdebug.log，看有没有收到请求；没有就说明请求根本没带调试标识
最易被忽略的其实是路径映射的“字符级对齐”——多一个斜杠、少一个字母、大小写不一致，在 Linux 容器里都会导致映射失败。别信“差不多”，/var/www/html 和 /var/www/html/ 是两个不同路径。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
