需先确认php与xdebug版本兼容：xdebug 3须用新配置项（如xdebug.mode=debug），且php.ini中启用zend_extension、设置xdebug.client_port=9003等；vscode仅装php debug插件，launch.json端口与之匹配，并正确配置pathmappings。
确认 PHP 和 Xdebug 版本兼容性
VSCode 本身不运行 PHP，它依赖本地已安装的 php 可执行文件和匹配的 xdebug 扩展。最常踩的坑是版本不兼容：Xdebug 3 不再支持 Xdebug 2 的配置项（如 xdebug.remote_enable），而 VSCode 的 PHP Debug 插件默认适配 Xdebug 3+。先在终端运行：
php -v php -m | grep xdebug
若输出含 Xdebug v3.x，则配置必须用新版参数；若为 v2.x，要么升级 Xdebug，要么在 php.ini 中保留旧参数（但建议升级）。注意 Windows 用户需确认 php.ini 是 CLI 模式实际加载的那个（可用 php --ini 查看路径）。
修改 php.ini 启用并监听 Xdebug 3
Xdebug 3 默认不监听外部连接，且默认关闭调试触发。需在 php.ini 中添加或修改以下段落（非注释状态）：
[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
关键点：
立即学习“PHP免费学习笔记（深入）”；
-
xdebug.mode=debug是 Xdebug 3 的启用开关（不是on或1） -
xdebug.start_with_request=yes表示每次请求自动开始调试（适合 CLI 或简单 Web 场景；Web 开发中也可设为trigger，配合浏览器插件手动触发） -
xdebug.client_port必须与 VSCode 的launch.json中port一致，默认是9003（Xdebug 2 是9000） -
xdebug.log强烈建议开启，出问题时直接查日志比猜快得多
VSCode 安装插件与配置 launch.json
仅安装 PHP Debug（由 Felix Becker 维护）即可，无需其他 PHP 插件辅助调试。安装后，在项目根目录创建 .vscode/launch.json：
{
"version": "0.2.0",
"configurations": [
{
"name": "Listen for Xdebug",
"type": "php",
"request": "launch",
"port": 9003,
"pathMappings": {
"/var/www/html/": "${workspaceFolder}/"
}
}
]
}
注意路径映射：
- 如果用 Docker 或 WSL，
pathMappings左侧是容器/远程服务器上的绝对路径，右侧是本地工作区路径 - 纯本地 Apache/Nginx + Windows，通常可简化为
"${workspaceFolder}/": "${workspaceFolder}/"（但不推荐省略，明确写更稳） - 没配
pathMappings会导致断点命中但变量显示undefined或跳转错文件
CLI 调试和 Web 调试的区别处理
CLI（命令行）调试直接按 F5 启动即可；Web 调试需确保请求能连上 Xdebug。常见失败原因：
- Apache/Nginx 配置未启用
php_value xdebug.mode debug（只靠php.ini不够，Web SAPI 可能被覆盖） - 浏览器没带
XDEBUG_SESSION_START=PHPSTORM（或任意值），且xdebug.start_with_request没设为yes或trigger - 防火墙或杀毒软件拦截了
9003端口（尤其 Windows Defender） - 多个 PHP 版本共存时，Web 服务器加载的是另一个
php.ini（检查phpinfo()页面里的Loaded Configuration File）
复杂点在于：Xdebug 日志里出现 Connection to client failed 时，90% 是路径映射或端口不一致；出现 Waiting for connection 却无响应，大概率是客户端（VSCode）根本没监听，或网络层被拦。
