VSCode调试PHP需Xdebug 3配合正确CLI配置：确认php -m显示xdebug、php --ini定位配置文件、设置xdebug.mode=debug及client_host/port、launch.json中pathMappings路径映射准确、端口统一为9003。
vscode 本身不内置 php 调试能力，必须配合 xdebug（推荐 v3.x）或 php-debug 扩展 + 正确的 php cli 配置才能断点调试。直接装个插件点“开始调试”大概率失败。
确认 PHP CLI 已启用 xdebug 并正确加载
这是最常卡住的一步。很多用户以为装了 Xdebug 就行，但 VSCode 调试走的是命令行 PHP（php -v 输出的版本），不是 Apache/Nginx 的模块版。
- 在终端运行
php -m | grep xdebug，有输出才表示 CLI 模式已加载 - 运行
php --ini查看配置文件路径，确保xdebug.ini（或类似名）被包含且未被注释 - Xdebug 3 必须显式启用远程调试：
xdebug.mode=debug，不是旧版的xdebug.remote_enable=1 -
xdebug.client_host应设为127.0.0.1（Windows/macOS）或host.docker.internal（Docker 容器内调试宿主机） - 检查
xdebug.start_with_request：设为yes可免手动触发，设为trigger则需带XDEBUG_SESSION_START=1参数或浏览器插件
VSCode 配置 launch.json 启动调试会话
项目根目录下创建 .vscode/launch.json，关键字段不能错。PHP 调试器依赖 pathMappings 把服务器路径映射到本地路径，否则断点不命中。
{
"version": "0.2.0",
"configurations": [
{
"name": "Listen for Xdebug",
"type": "php",
"request": "launch",
"port": 9003,
"pathMappings": {
"/var/www/html/": "${workspaceFolder}/"
},
"xdebugSettings": {
"max_children": 128,
"show_hidden": true,
"max_depth": 10,
"max_data": 1024
}
}
]
}
-
port必须与xdebug.client_port一致（Xdebug 3 默认9003，不是旧版9000） -
pathMappings左侧是 PHP 进程看到的绝对路径（如 Docker 中的/var/www/html/），右侧是本地工作区路径 - 如果用 PHP 内置服务器（
php -S localhost:8000），pathMappings左侧通常就是${workspaceFolder}/
触发调试的三种常用方式
不是所有请求都会进调试器，取决于 Xdebug 如何被激活。
- URL 参数法：在浏览器访问
http://localhost:8000/index.php?XDEBUG_SESSION_START=1（前提是xdebug.start_with_request=trigger） - Cookie 法：安装浏览器插件（如 Xdebug Helper），点击图标启用后自动注入
XDEBUG_SESSIONCookie - CLI 脚本调试：终端执行
XDEBUG_CONFIG="idekey=VSCODE" php script.php，同时 VSCode 启动Listen for Xdebug配置 - 注意：若
xdebug.start_with_request=yes，则所有请求都会尝试连接，无需额外参数，但性能开销略大
常见错误现象与快速定位
断点灰色、控制台无响应、VSCode 显示 “Waiting for a debug session…” —— 大概率是通信链路某处断了。
立即学习“PHP免费学习笔记（深入）”；
- VSCode 控制台输出里搜
connection refused或timeout：说明 Xdebug 找不到 IDE，检查xdebug.client_host/port和launch.json的port是否一致 - 断点显示为空心圆（未绑定）：
pathMappings路径不匹配，或 PHP 实际执行路径和配置里写的不一致（可用getcwd()或__FILE__打印验证） - 调试时变量显示
max_children或max_data太小，调大即可 - 修改代码后断点仍停在旧位置：PHP OPcache 缓存了脚本，临时关闭
opcache.enable=0或重启 PHP 进程
真正麻烦的从来不是配通，而是路径映射和端口对齐——这两项错一个字符，整个调试就静默失败。建议先用 phpinfo() 确认 Xdebug 加载状态，再比对 php -i | grep -A5 -B5 xdebug 输出和 launch.json 里的值。
