VS Code 调试 PHP 必须同时配置 Xdebug 3（PHP 端）和 PHP Debug 插件（VS Code 端），关键在于 php.ini 中启用 zend_extension、设置 xdebug.mode=debug 与 client_port=9003，并在 launch.json 中匹配 port 和 pathMappings。
VS Code 能调试 PHP，但不是开箱即用——必须同时配对 Xdebug 3（PHP 端）和 PHP Debug 插件（VS Code 端），缺一不可。断点不触发、连接超时、变量为空，90% 都是这两端配置没对齐。
确认 Xdebug 3 已正确加载并监听本地
这是整个流程的地基。很多人卡在“点了 F5 没反应”，其实 VS Code 根本没收到连接请求。
- 终端运行
php -m | grep xdebug，有输出才说明扩展已启用；无输出就别往下走了 - 检查
php.ini（用php --ini找准确路径），Xdebug 3 必须用以下写法（不是旧版的xdebug.remote_enable=1）：
[xdebug] 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.client_port=9003是关键，默认值，VS Code 插件也默认连这个端口；若改了，两边必须同步改 - 重启 Web 服务（Apache/Nginx）或 PHP 内置服务器；Windows 用户若用 phpstudy/XAMPP，请在控制面板里「重启服务」而非只重启 Apache
VS Code 中装对插件 + 配准 launch.json
只装「PHP」扩展不够，它只提供语法高亮和跳转；真正收 Xdebug 连接的是 PHP Debug 插件（作者：felixfbecker）。
- 在扩展市场搜
PHP Debug，安装后重启 VS Code - 打开项目根目录 → 按
F5→ 选PHP→ 自动生成.vscode/launch.json - 重点改两项：
port和pathMappings，其余保持默认即可
{
"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，XAMPP 是C:/xampp/htdocs），右边是你的本地项目文件夹；映射错一个字符，断点就永远不命中
触发调试：URL 参数 or CLI 脚本？怎么选
两种方式本质一样，都是让 PHP 主动连回 VS Code。区别在于你当前开发场景。
立即学习“PHP免费学习笔记（深入）”；
-
Web 请求调试（推荐）：访问
http://localhost/index.php?XDEBUG_SESSION_START=1，或装浏览器插件「Xdebug Helper」自动加参数 -
CLI 脚本调试（适合命令行工具）：在
launch.json中额外加一个配置：
{
"name": "Launch currently open script",
"type": "php",
"request": "launch",
"program": "${file}",
"cwd": "${fileDirname}",
"port": 9003
}
- 然后打开
test.php→ 按F5→ 选这个配置 → 就会直接执行该脚本并进断点 - 注意：CLI 方式下
xdebug.start_with_request=yes仍需开启，否则不触发
断点生效但变量看不到？别急着重装
常见现象：程序停在断点，调用堆栈正常，但「变量」面板空空如也，或显示 undefined。
- 先看右下角状态栏：是否显示
Xdebug listening on 127.0.0.1:9003？没显示说明监听根本没起来 - 打开
xdebug.log（按配置路径找），搜索Connection failed或Failed to connect，大概率是防火墙拦截、Docker 网络不通、或client_host写成了localhost（某些系统解析失败，必须用127.0.0.1） - 如果用 Docker，
xdebug.client_host不能写127.0.0.1（那是容器自己），得填宿主机 IP（如172.17.0.1），且pathMappings左边必须是容器内路径
最常被忽略的一点：Xdebug 日志默认不开启，而它是唯一能告诉你“到底连没连上”的证据。只要调试异常，第一反应不是重装，而是打开 xdebug.log 看第一行错误。
