断点不触发等问题主因是php、xdebug版本/路径/端口未对齐。需确认cli的php.ini路径、xdebug 3正确加载、五项配置（zend_extension、xdebug.mode等）无误、launch.json端口与pathmappings严格匹配，并确保浏览器或cli主动触发调试会话。
断点不触发、红点变空心圆、变量全显示 undefined，八成不是 VSCode 没装对插件，而是 PHP 和 Xdebug 的版本、路径、端口三者没对齐。Xdebug 3 + PHP 8.0+ 是当前主流组合，但混用旧参数或错配路径，调试会完全静默失败。
确认 PHP CLI 加载的 php.ini 和 Xdebug 版本
VSCode 调试走的是 PHP 命令行（CLI）环境，不是 Apache 或 Nginx 的配置。很多人改了 Web 服务的 php.ini，却忘了 CLI 用的是另一个文件。
- 在终端运行
php --ini，看Loaded Configuration File那一行路径 —— 这才是你要编辑的文件 - 运行
php -v，输出里必须含with Xdebug v3.x；没有就说明扩展根本没加载 - 运行
php --ri xdebug，检查Version行和Supports phpinfo()是否为enabled - 如果
php --ri xdebug输出里还出现xdebug.remote_host或xdebug.remote_port，说明配置里混了 Xdebug 2 的废弃参数，得删干净
php.ini 必须写对这五项（Xdebug 3）
Xdebug 3 彻底弃用 remote_* 系列参数，写进去不仅无效，还可能让 PHP 启动失败或跳过调试逻辑。只保留且必须写全以下五项：
-
zend_extension=xdebug（Linux/macOS）或zend_extension=php_xdebug.dll（Windows），路径要绝对准确，含空格需加引号 -
xdebug.mode=debug（不是on、1或develop） -
xdebug.client_host=127.0.0.1（Docker/WSL 场景下可能需改成宿主机网关，如10.0.2.2） -
xdebug.client_port=9003（Xdebug 3 默认端口，不是旧版9000） -
xdebug.start_with_request=trigger（推荐手动触发，避免无请求时持续连接；设为yes则每次请求都连）
改完后重启终端（或整个 VSCode），再跑 php -v 验证。
launch.json 的 port 和 pathMappings 必须字面级对齐
port 错一位、pathMappings 左右路径多一个斜杠或大小写不一致，断点就永远是空心圆 —— VSCode 不报错，只安静忽略。
-
"port": 9003必须和php.ini中的xdebug.client_port完全一致 -
pathMappings左边是 PHP 进程看到的**绝对路径**，比如：
– Docker 容器内："/app/"
– macOS Apache："/Library/WebServer/Documents/"
– WSL："/mnt/c/xampp/htdocs/"（注意正斜杠） - 右边统一用
"${workspaceFolder}/"，结尾建议带斜杠，避免 POSIX 路径匹配失败 - 本地开发用
php -S内置服务器可省略pathMappings；但只要用了 Apache/Nginx/FPM/Docker，就必须显式配置
典型写法："pathMappings": { "/var/www/html/": "${workspaceFolder}/" } —— 顺序反了或漏斜杠，映射就失效。
浏览器或 CLI 必须主动触发 Xdebug 会话
VSCode 不会自动向 PHP 发起调试连接，它只是“监听”。你得让 PHP 主动找过来，方式有两种：
- 装官方
Xdebug Helper插件（Chrome/Firefox），右键图标选Debug（不是Profile或Off）；默认发XDEBUG_SESSION_START=PHPSTORM - VSCode 的
launch.json中ideKey必须与之匹配（默认就是PHPSTORM）；若改过，插件设置里也得同步改 - 命令行测试时，手动加参数：
curl "http://localhost/index.php?XDEBUG_SESSION_START=PHPSTORM" - 别依赖
xdebug.start_with_request=yes就万事大吉 —— 它只在 Web 请求中生效，CLI 脚本仍需export XDEBUG_CONFIG="idekey=PHPSTORM"
如果 VSCode 底部状态栏一直显示 Listening on port 9003 却没反应，先查浏览器是否真发出了带调试参数的请求，再查防火墙或端口是否被占用。
最常被忽略的其实是 php --ini 看到的路径和你实际编辑的 php.ini 不是一份，以及 pathMappings 左右路径的尾部斜杠、大小写、空格这些“看不见的字符”。调试连不上，先盯住这两处，比重装插件有效得多。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
