VS Code调试PHP需Xdebug与PHP Debug插件协同，关键在php.ini与launch.json配置严格匹配：Xdebug 3用client_port=9003、mode=debug；Xdebug 2用remote_port=9000；端口、路径映射、IDE key须一致，且需重启服务并验证加载。
VS Code 本身不内置 PHP 调试能力，必须靠 Xdebug + PHP Debug 扩展协同工作；配置失败绝大多数是因为 php.ini 中的 Xdebug 设置与 VS Code 的 launch.json 不匹配，或端口被占用、IDE key 错位。
确认 PHP 环境和 Xdebug 版本兼容性
Xdebug 3 和 Xdebug 2 的配置项完全不同，混用必报错。先在终端运行：
php -v
看输出里是否含 Xdebug v3.x 或 Xdebug v2.x。再运行：
php --ini
找到正在加载的 php.ini 路径（不是 .user.ini 或其他）。打开它，删掉旧的 [XDebug] 区块（如果存在），再按版本写入对应配置：
立即学习“PHP免费学习笔记（深入）”；
- Xdebug 3（推荐）：添加以下内容到
php.ini末尾
zend_extension=xdebug<br>xdebug.mode=debug<br>xdebug.start_with_request=yes<br>xdebug.client_host=127.0.0.1<br>xdebug.client_port=9003<br>xdebug.log=/tmp/xdebug.log
- Xdebug 2：用这套（注意函数名和参数差异）
zend_extension=xdebug<br>xdebug.remote_enable=1<br>xdebug.remote_host=127.0.0.1<br>xdebug.remote_port=9000<br>xdebug.remote_autostart=1<br>xdebug.remote_log=/tmp/xdebug.log
改完重启 Web 服务（如 Apache/Nginx）或 PHP-FPM 进程，再执行 php -m | grep xdebug 确认已加载。
安装并启用 VS Code 的 PHP Debug 插件
在 VS Code 扩展市场搜 PHP Debug，选作者是 Felix Becker 的那个（官方推荐）。装好后重启 VS Code。它不会自动激活——只有你打开一个 .php 文件，并且项目根目录下有 .vscode/launch.json 时，调试面板才会显示 PHP 配置选项。
关键点：
- 不要手动创建空的
launch.json就算完事，必须让插件生成模板（点击左上角「运行」→「打开配置」→ 选「PHP」） - 生成的默认配置中，
port必须和php.ini里的client_port（Xdebug 3）或remote_port（Xdebug 2）严格一致 - 如果你用的是 WSL、Docker 或远程服务器，
pathMappings必须正确映射本地路径到服务器上的绝对路径，例如："${workspaceFolder}/": "/var/www/html/"
启动调试前必做的三件事
很多人卡在这一步：断点打了，F5 按了，但没反应。先检查：
- 浏览器是否带了 Xdebug 触发参数？Xdebug 3 默认开启
start_with_request=yes，所以不用额外加?XDEBUG_SESSION_START=1；但如果你关了它，就得手动加，或装浏览器插件（如 Xdebug Helper）并启用 - VS Code 是否已打开项目根目录（即含
index.php或入口文件的文件夹），而不是只打开单个文件 - 终端里运行
netstat -an | grep 9003（或你设的端口），确认该端口没被 PhpStorm、其他 VS Code 窗口或残留进程占用；若被占，改php.ini和launch.json为 9004 并重启
调试时，断点只对 PHP CLI 脚本或 Web 请求生效，对纯 HTML 文件无效；如果用的是内置 PHP Server（php -S），确保它是在 VS Code 终端里启动的，否则 Xdebug 无法连接。
常见错误现象与对应修复
Connection refused：Xdebug 尝试连 localhost:9003 失败 → 检查 php.ini 的 client_host 是否写成 localhost（某些系统解析慢），统一改 127.0.0.1；再确认 launch.json 的 port 和 pathMappings 没拼错。
Breakpoint ignored：断点灰色 → 文件路径映射错误，或 PHP 正在运行的脚本不在你设断点的路径下（比如请求的是 /api/user.php，但你在 /src/User.php 打了断点却没被调用）。
Xdebug not loaded：运行 phpinfo() 页面里看不到 Xdebug 区块 → 检查 php.ini 路径是否正确，zend_extension 值是否指向真实存在的 xdebug.so（Linux/macOS）或 php_xdebug.dll（Windows）文件，扩展名和路径别写错。
Windows 下还容易因杀毒软件拦截 9003 端口，临时关闭试试；Mac 上如果用了 Rosetta，确保 Xdebug 扩展是为同架构编译的。
