Xdebug连不上IDE首要检查xdebug.client_host配置：Docker Desktop用host.docker.internal，Linux需填宿主机真实IP并确保可达；断点跳过是因本地与容器路径映射不一致；连接拒绝需确认端口映射、防火墙及IDE监听状态；性能卡顿源于xdebug.mode和start_with_request未按需配置。
docker容器里Xdebug连不上IDE？先看client_host设对没
绝大多数连接失败，根源在 xdebug.client_host 值填错了。Docker容器默认无法直接解析宿主机的 localhost 或 127.0.0.1 —— 它会指向容器自己。
正确做法取决于你的运行环境：
- Docker Desktop（macOS/Windows）：用
host.docker.internal，这是Docker内置的DNS别名 - Linux原生Docker：必须手动指定宿主机真实IP（比如
192.168.1.5），且确保该IP在容器内能ping通 - 用
xdebug.discover_client_host=1是高危操作，容易被劫持或连错地址，不推荐
验证方式：进容器执行 ping -c 1 host.docker.internal 或 telnet 192.168.1.5 9003，不通就别往下试了。
断点一直跳过？路径映射没对上
IDE显示“断点已设置”，但执行时完全不中断，八成是本地文件路径和容器内路径没映射一致。Xdebug把断点位置发给IDE后，IDE按自己本地路径去找文件，找不到就忽略。
立即学习“PHP免费学习笔记（深入）”；
关键检查点：
- 确认
docker-compose.yml中挂载路径写法：比如./src:/var/www/html，不是./src/:/var/www/html/（末尾斜杠差异会导致路径拼接出错） - PHPStorm里“Servers”配置中的“Absolute path on the server”必须严格匹配容器内实际路径，例如填
/var/www/html，不能少字符或多空格 - 运行
php --ri xdebug，看输出里Loaded with行是否包含你改过的xdebug.ini路径，避免配置被其他ini覆盖
调试日志里满屏“Connection refused”？端口或防火墙卡住了
xdebug.log 文件里反复出现 ERROR: Could not connect to client，说明Xdebug尝试发包失败，不是代码问题，是网络链路断了。
分三步定位：
- 查容器是否暴露了调试端口：
docker-compose.yml中必须有ports: ["9003:9003"]（注意是宿主机:容器，不是反过来） - 查宿主机防火墙：macOS系统偏好→安全性与隐私→防火墙→高级，确认允许
phpstorm或code接收传入连接；Linux用户检查ufw或iptables - 查IDE监听状态：PHPStorm需点击“Start Listening for PHP Debug Connections”，VS Code要确保
launch.json的port和xdebug.client_port一致，且没被其他进程占用（比如另一个PHPStorm实例）
启用Xdebug后接口慢得像卡住？mode和trigger没配好
Xdebug 3.x 默认开启所有模式，xdebug.mode=develop,debug 会让每个请求都做堆栈收集、变量捕获，性能暴跌是必然的。
开发时真正需要的只是“按需调试”，不是“永远开着”：
- 改成
xdebug.mode=debug，关掉develop模式里的错误追踪和参数收集 - 把
xdebug.start_with_request=yes改成trigger，然后用浏览器插件（Xdebug Helper）或加?XDEBUG_SESSION_START=1参数触发 - CLI脚本调试时，记得加环境变量：
XDEBUG_CONFIG="idekey=PHPSTORM" php script.php
最常被忽略的一点：Docker里PHP-FPM和CLI可能加载不同php.ini，php -m | grep xdebug 和 php-fpm -m | grep xdebug 得分别验证，否则网页能调、命令行调不了，或者反过来。
