VSCode调试PHP需扩展+外部PHP环境+Xdebug配合，核心卡点是Xdebug版本与PHP/SAPI匹配、launch.json端口（9003）与xdebug.client_port一致、pathMappings路径绝对准确、xdebug.start_with_request=trigger手动触发，Docker/WSL需修正client_host。
VSCode 本身不内置 PHP 运行或调试能力，必须通过扩展 + 外部 PHP 环境 + Xdebug 配合才能完成完整调试流程。直接装个插件点“开始调试”大概率失败，核心卡点在 xdebug 版本与 PHP 版本、SAPI 类型（CLI / Apache / FPM）是否匹配，以及 VSCode 的 launch.json 配置是否指向真实监听地址和端口。
确认 PHP 和 Xdebug 已正确安装并启用
先在终端运行 php -v 确认 PHP 可用；再执行 php -m | grep xdebug 或 php --ini 查看配置文件路径，打开对应 php.ini，检查是否存在且未被注释的 zend_extension=...xdebug.so（Linux/macOS）或 php_xdebug.dll（Windows）行。Xdebug 3+ 默认关闭远程调试，必须显式启用：
zend_extension=xdebug xdebug.mode=debug xdebug.client_host=127.0.0.1 xdebug.client_port=9003 xdebug.start_with_request=trigger
注意：xdebug.client_port 默认是 9003（不是旧版的 9000），VSCode 的 launch.json 必须与之严格一致；xdebug.start_with_request=trigger 表示需手动触发（如加 ?XDEBUG_SESSION_START=1 参数或使用浏览器插件），避免无请求时持续连接。
安装 PHP Debug 扩展并配置 launch.json
VSCode 中安装 PHP Debug（作者：Felix Becker），重启后按 Ctrl+Shift+P（Windows/Linux）或 Cmd+Shift+P（macOS），输入 PHP: Select Interpreter 并指定你系统中真实的 php 可执行文件路径（例如 /usr/bin/php 或 C:\php\php.exe）。然后在项目根目录创建 .vscode/launch.json，关键字段如下：
立即学习“PHP免费学习笔记（深入）”；
本书图文并茂，详细讲解了使用LAMP（PHP）脚本语言开发动态Web程序的方法，如架设WAMP平台，安装与配置开源Moodle平台，PHP程序设计技术，开发用户注册与验证模块，架设LAMP平台。 本书适合计算机及其相关专业本、专科学生作为学习LAMP（PHP）程序设计或动态Web编程的教材使用，也适合对动态Web编程感兴趣的读者自觉使用，对LAMP（PHP）程序设计人员也具有一定的参考价值。
{
"version": "0.2.0",
"configurations": [
{
"name": "Listen for Xdebug",
"type": "php",
"request": "launch",
"port": 9003,
"pathMappings": {
"/var/www/html/": "${workspaceFolder}/"
}
}
]
}
pathMappings 是最常出错的地方：左侧是服务器上 PHP 脚本的**绝对路径**（比如 Docker 容器内 /var/www/html/，或本地 Apache 的 /Library/WebServer/Documents/），右侧是 VSCode 当前打开的文件夹路径。两者必须逐字符对齐，否则断点不命中。
验证 Xdebug 是否连通，避开常见网络陷阱
启动 VSCode 调试器（点击左侧调试图标 → 选择 “Listen for Xdebug” → 点绿色 ▶️ 按钮），此时 VSCode 会在 9003 端口监听；接着在浏览器访问目标 PHP 页面，并确保触发了 Xdebug（例如 URL 加 ?XDEBUG_SESSION_START=1，或用 Xdebug Helper 浏览器插件启用）。如果没反应，检查以下几点：
-
防火墙是否拦截了
9003端口（尤其 Windows Defender 或 macOS 防火墙） - 若用 Docker，宿主机 VSCode 无法直连容器内 PHP 的
127.0.0.1，应设xdebug.client_host=host.docker.internal（Docker Desktop）或宿主机 IP -
phpinfo()页面中搜索 “xdebug” ，确认Xdebug模块已加载，且idekey显示为VSCODE（PHP Debug 扩展默认值） - VSCode 控制台（Output → PHP Debug）有无报错，如
Connection refused说明端口不通，Invalid response常因 Xdebug 版本与扩展不兼容
Xdebug 3 的配置项命名和行为与 2.x 差异很大，xdebug.remote_enable 这类旧参数已失效；pathMappings 的路径方向容易写反；Docker 或 WSL 环境下网络栈隔离是高频故障源——这些不是配置漏了，而是环境假设错了。
