需先确认Xdebug版本为3.x并启用调试模式，再配置php.ini中zend_extension、xdebug.mode=debug、xdebug.client_host、xdebug.client_port=9003及xdebug.log，最后在VS Code中安装PHP Debug插件并正确设置launch.json的port和pathMappings。
确认 Xdebug 版本和 PHP 运行模式
VS Code 本身不运行 PHP，它依赖本地或远程的 PHP 环境 + Xdebug 扩展。先在终端执行 php -v 和 php -m | grep xdebug，确认 Xdebug 已加载。注意：Xdebug 3 和 Xdebug 2 的配置项完全不同，且 Xdebug 3 默认不兼容旧版 IDE 配置。若输出中含 Xdebug v3.x，后续所有 zend_extension 路径、xdebug.mode、xdebug.client_host 等必须按 v3 规范写；若仍是 v2，需停用并升级，因为 VS Code 的 PHP Debug 插件已不再维护对 Xdebug 2 的兼容支持。
修改 php.ini 启用远程调试（Xdebug 3）
找到正在使用的 php.ini（用 php --ini 查），在末尾添加以下内容（根据实际环境调整）：
zend_extension=xdebug.so 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.mode=debug是 Xdebug 3 的必需开关，仅设zend_extension不会启动调试 - 本地开发时
xdebug.client_host通常为127.0.0.1；若 PHP 运行在 Docker 容器内且 VS Code 在宿主机，这里要填宿主机网关（如host.docker.internal或172.17.0.1） -
端口必须与 VS Code 中
launch.json的port一致，默认是9003（Xdebug 2 是9000） -
xdebug.log强烈建议开启，出问题时直接看日志比猜配置快得多
VS Code 安装插件并配置 launch.json
安装官方扩展：PHP Debug（作者 Felix Becker）。然后在项目根目录创建 .vscode/launch.json，内容如下：
立即学习“PHP免费学习笔记（深入）”；
{
"version": "0.2.0",
"configurations": [
{
"name": "Listen for Xdebug",
"type": "php",
"request": "launch",
"port": 9003,
"pathMappings": {
"/var/www/html/": "${workspaceFolder}/"
}
}
]
}
说明：
-
port必须与php.ini中的xdebug.client_port完全一致 -
pathMappings是远程调试的核心映射：左边是服务器上 PHP 文件的绝对路径（如 Docker 内/var/www/html/index.php），右边是本地对应文件夹（${workspaceFolder}即 VS Code 当前打开的文件夹） - 如果 PHP 在远程服务器（非 Docker），且你用 SFTP 同步代码，
pathMappings左边应填远程服务器上的真实路径，如/home/user/project/
启动调试并验证断点是否生效
启动调试前务必：
- 重启 Web 服务或 PHP-FPM（
sudo systemctl restart php-fpm或sudo service apache2 restart）使php.ini生效 - 在 VS Code 中点击左侧调试图标 → 选择
Listen for Xdebug→ 点击绿色 ▶️ 启动监听 - 在 PHP 文件中打一个断点（如
index.php第一行），然后在浏览器访问该 URL（如http://localhost/index.php）
如果断点未命中，立刻检查 /tmp/xdebug.log：常见错误包括连接被拒绝（端口不匹配）、路径映射失败（Could not map file）、Xdebug 尝试连错 IP（如连了 127.0.0.1 但实际需连宿主机 IP）。Docker 用户最容易卡在 client_host 配置上——容器里 127.0.0.1 指自己，不是宿主机。
