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
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=127.0.0.1
xdebug.client_port=9003
xdebug.log=/tmp/xdebug.log
- Xdebug 2：用这套（注意函数名和参数差异）
zend_extension=xdebug
xdebug.remote_enable=1
xdebug.remote_host=127.0.0.1
xdebug.remote_port=9000
xdebug.remote_autostart=1
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 配置选项。
关键点：
大家都知道，在进行J2EE项目的开发过程中，在调试阶段如果只是修改了页面是不需要重启应用服务器的，比如不需要重启Tomcat。只需要在浏览器中 进行页面刷新即可。其实之所以不用重启Tomcat等应用服务器，其根本原因是因为我们可以在应用服务器的配置文件中设置虚拟目录，这样就可以知道web 项目所在的目录，于是就可以省去打包、然后再重新发布到服务器的步骤。感兴趣的朋友可以过来看看
- 不要手动创建空的
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 扩展是为同架构编译的。
