xdebug远程调试连不上90%是配置不匹配所致，需确认xdebug.mode=debug、client_host与vs code的port（9003）一致，并正确设置pathmappings和trigger机制。
Xdebug 远程调试连不上，90% 是 xdebug.mode、xdebug.client_host 或 VS Code 的 launch.json 配置不匹配导致的，不是插件没装或端口被占——先别急着重装。
确认 Xdebug 3 的启用模式和触发方式
Xdebug 3 彻底改了启动逻辑，xdebug.remote_enable 这类旧配置已失效，必须用 xdebug.mode 控制行为。默认是 off，不手动开就完全不工作。
-
xdebug.mode = debug是基础要求；如果还要做性能分析，可加profile，但调试阶段只开debug更干净 - 触发调试不能只靠
xdebug.start_with_request = yes（会强制所有请求都连 IDE，线上误开极危险），推荐用trigger_value+ 浏览器插件或 GET 参数，例如：xdebug.start_with_request = trigger+ URL 加?XDEBUG_SESSION_START=1 - 检查
phpinfo()输出里是否真有Xdebug模块，且Directive表中xdebug.mode值为debug，不是off或空
VS Code 的 launch.json 必须匹配 Xdebug 的连接目标
VS Code 不“监听 PHP”，而是监听 Xdebug 主动发起的连接；所以 launch.json 里的 port 是 VS Code 自己监听的端口（默认 9003），而 xdebug.client_port 必须和它一致 —— 不是 9000，也不是 9001。
- PHP 容器/本机运行时，
xdebug.client_host要填对：本地开发填127.0.0.1；Docker 容器里调宿主机 VS Code，得填宿主机在 Docker 网络中的 IP（如host.docker.internal，Windows/macOS 支持，Linux 需额外配置） -
pathMappings是关键：PHP 脚本路径（/var/www/html/index.php）和 VS Code 工作区路径（/Users/you/project）必须严格映射，路径末尾斜杠、大小写、符号链接都会导致断点不命中 - 示例最小可用配置：
{ "version": "0.2.0", "configurations": [ { "name": "Listen for Xdebug", "type": "php", "request": "launch", "port": 9003, "pathMappings": { "/var/www/html": "${workspaceFolder}" } } ] }
常见连不上现象和对应排查点
看到 “waiting for Xdebug connection” 却一直转圈？不是网络问题，大概率是握手参数错位。
- 浏览器访问后，
tail -f /var/log/apache2/error.log或php -S终端里没任何 Xdebug 连接日志 → 检查xdebug.mode和xdebug.start_with_request是否生效，再确认 URL 是否带有效触发参数 - VS Code 显示 “connection closed” 或日志里报
Connection refused→xdebug.client_host填错了（比如容器里填了127.0.0.1，实际该连宿主机）；或防火墙/SELinux 拦了 9003 端口（Linux 上常被忽略） - 能连上但断点全灰、不触发 →
pathMappings路径不一致，或 PHP 脚本用了require_once __DIR__.'/../vendor/autoload.php'这类相对路径引入，VS Code 无法识别真实文件位置
最易被忽略的是：Xdebug 3 默认只允许 localhost 回调，xdebug.client_host 如果填了非本地地址（比如 Docker 场景下的 host.docker.internal），必须同时设 xdebug.discover_client_host = false，否则它会强行覆盖成 127.0.0.1。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
