VSCode调试PHP必须配置xdebug 3并正确设置监听参数。需验证php -v含Xdebug v3.x、php.ini中启用xdebug.mode=debug、xdebug.client_host/port匹配launch.json，且CLI调试需显式加-d参数，容器场景须精确配置pathMappings。
vscode 本身不内置 php 调试能力，必须依赖 xdebug 或 phpstan（静态分析）以外的运行时调试器 —— 实际能用的只有 xdebug（v3.x 推荐）或 zend_debugger（已淘汰）。没装对扩展、没配对端口、没启对 php cli 配置，launch.json 写得再漂亮也断不进第一行。
确认 PHP 环境已启用 xdebug 3
先验证不是 VSCode 的问题，而是 PHP 是否真在跑 xdebug：
- 终端执行
php -v，输出里必须含with Xdebug v3.x.x，不含则未加载 - 执行
php --ini查看配置文件路径，打开php.ini或conf.d/xdebug.ini - xdebug 3 要求显式启用：确保有
xdebug.mode=debug（不是旧版的xdebug.remote_enable=1） - 关键监听配置：
xdebug.client_host=127.0.0.1（Docker 或 WSL 需换为宿主机 IP）、xdebug.client_port=9003（xdebug 3 默认端口，不是 9000） - 重启 web server（如 Apache/Nginx）或 PHP-FPM，CLI 模式下调试需额外加
-d xdebug.mode=debug
VSCode 中安装并配置 PHP Debug 扩展
微软官方维护的 PHP Debug 扩展（作者 felixfbecker）是唯一推荐选择，其他“PHP Debugger”多为仿冒或过期项目：
- VSCode 扩展市场搜
PHP Debug，安装后重启 - 按
Ctrl+Shift+P（Win/Linux）或Cmd+Shift+P（Mac），输入PHP: Locate Composer可选配自动发现，非必需 - 重点：该扩展不自动读取
php.ini，必须手动告诉它 xdebug 监听地址 —— 这步漏掉，VSCode 根本不会连过去 - 项目根目录建
.vscode/launch.json，至少包含一个configurations项，type必须为php，request为launch或attach
区分 launch 和 attach 两种调试模式
launch 是 VSCode 启动 PHP 脚本并接管调试；attach 是 VSCode 主动连接已在运行的 PHP 进程（如 Web 请求、CLI 长进程）：
- 调试单个脚本（如
test.php）：用launch，program字段填绝对路径或${file} - 调试 Web 请求（Apache/Nginx + PHP-FPM）：必须用
attach，且 PHP 进程得提前开启 xdebug 并监听，否则请求一过就断 -
attach模式下必设port（默认9003），与xdebug.client_port严格一致；pathMappings必须配准，例如"pathMappings": { "/var/www/html/": "${workspaceFolder}/" } - Web 调试常配合浏览器插件（如 Xdebug Helper），给请求头加
XDEBUG_SESSION_START=PHPSTORM（值任意，但需与idekey匹配）
常见断点不命中与超时问题
断点灰色、控制台报 Could not connect to debugging client、或等 30 秒后超时，基本都卡在这几处：
立即学习“PHP免费学习笔记（深入）”；
- xdebug 3 默认关闭 CLI 调试：调试命令行脚本要加
php -d xdebug.mode=debug -d xdebug.start_with_request=yes script.php - 防火墙或 Docker 网络阻断 9003 端口：宿主机 telnet
127.0.0.1 9003应通；WSL2 需在 Windows 上开例外，Docker 则要在docker run加-p 9003:9003 -
launch.json里port写成9000（xdebug 2 风格）却不改 php.ini，两边端口错位 - 使用
symfony serve或php -S内置服务器时，xdebug 不会自动注入，需手动加查询参数：?XDEBUG_SESSION_START=1
真正麻烦的从来不是配置步骤，而是 xdebug 3 的 mode 机制、端口变更、以及 pathMappings 在容器/远程场景下的路径映射误差 —— 这些地方错一个字符，断点就永远灰着。
