必须先运行php --ini和php -v确认CLI加载的php.ini路径及Xdebug是否启用，否则后续所有配置均无效；90%的断点不触发、变量undefined、空心圆等问题源于此。
php --ini 和 php -v 必须先跑一遍，否则所有后续配置都是空中楼阁。断点不触发、变量显示 undefined、断点图标变空心圆——90% 是 CLI 加载的 php.ini 路径错了，或 Xdebug 根本没启用。
确认 PHP CLI 实际加载的 php.ini 路径
VSCode 调试走的是 PHP 命令行（CLI）环境，和 Apache/Nginx 的配置完全无关。很多人改了 C:\xampp\apache\bin\php.ini，但 php -v 用的是 C:\xampp\php\php.ini，结果白配。
- 终端执行
php --ini，盯住Loaded Configuration File那一行路径 - 再执行
php -v，输出里必须含with Xdebug字样；没有就说明这个php.ini没启用 Xdebug - Windows 用户：WAMP/XAMPP 默认有两套
php.ini，CLI 用的是 PHP 安装目录下的那个 - macOS/Linux 用户：Homebrew 安装的 PHP，路径通常是
/usr/local/etc/php/X.Y/php.ini，别去碰/etc/php.ini - 改完
php.ini后，必须重启 VSCode 终端（或整个 VSCode），否则php -v看不到变化
区分 Xdebug 2 和 Xdebug 3 的配置项
xdebug.remote_enable=1 在 Xdebug 3 中已彻底废弃，写进去不仅无效，还可能让 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.so（Linux/macOS）或zend_extension=php_xdebug.dll（Windows） - 别在 Xdebug 3 配置里留
xdebug.remote_host这类字段，它会直接导致调试连接失败
pathMappings 映射必须严格匹配服务器路径与本地路径
这是断点不生效的最高频原因。Xdebug 发送的是服务器上 PHP 脚本的绝对路径（比如 /var/www/html/index.php），VSCode 必须知道它对应你本地哪个文件夹。漏写、写反、斜杠方向错，都会让断点变成空心圆。
- 映射格式必须是 POSIX 风格：用正斜杠
/，不是反斜杠\ - Docker 场景：容器内路径是
/app/，本地项目在${workspaceFolder}，那就写"pathMappings": { "/app/": "${workspaceFolder}/" } - WSL 场景：Windows 本地路径是
C:\Users\me\project，WSL 内路径是/mnt/c/Users/me/project，映射左侧就得填/mnt/c/Users/me/project/ - 纯本地开发（如 MAMP）：Apache DocumentRoot 是
/Applications/MAMP/htdocs，那左侧就填这个，右侧填${workspaceFolder} - Windows 用户尤其注意：不能写
C:\project，得转成/c/project或/mnt/c/project（取决于 WSL 版本）
launch.json 的 port 必须和 xdebug.client_port 严格一致
VSCode 的 launch.json 不是模板填充游戏，port 字段必须和 php.ini 里的 xdebug.client_port 一模一样，差一个数字都不行。
立即学习“PHP免费学习笔记（深入）”；
- Xdebug 3 默认是
9003，不是旧版的9000；很多教程照抄旧值，直接导致“连接超时” - launch.json 示例片段（Xdebug 3）：
{
"version": "0.2.0",
"configurations": [
{
"name": "Listen for Xdebug",
"type": "php",
"request": "launch",
"port": 9003,
"pathMappings": {
"/var/www/html/": "${workspaceFolder}/"
}
}
]
}
xdebug.client_host 可能得改成宿主机网关（如 10.0.2.2），而不是 127.0.0.1
php.ini 中加一行 xdebug.log=/tmp/xdebug.log（Linux/macOS）或 xdebug.log=C:\xdebug.log（Windows），出问题直接查日志，比猜快得多pathMappings 和 php.ini 路径错配，是两个最隐蔽也最常被忽略的点。前者错，断点不命中但无报错；后者错，Xdebug 根本不加载，连日志都不会写。 
