Xdebug 在 Docker 中连不上 IDE 的主因是 client_host 配置错误、9003 端口未映射或 IDE 未监听；需在 docker-compose.yml 显式映射 -"9003:9003"，Linux 用宿主机 IP（非 localhost），Mac/Win 可用 host.docker.internal，xdebug.mode=debug 必须启用，IDE 端口设为 9003 并配置 path mapping，同时检查防火墙与 xdebug.log。
Xdebug 在 Docker 里连不上 IDE，99% 是 client_host 指错了、端口没映射对、或 IDE 根本没在监听——不是配置少几行，而是关键项错一个就全盘失效。
docker-compose.yml 必须暴露并映射 9003 端口
Docker 容器默认隔离网络，Xdebug 作为客户端要主动连宿主机的 IDE，必须让 9003 端口“通出去”。只写 xdebug.client_port=9003 不够，ports 字段漏掉就会静默失败。
- PHP 服务块里必须显式声明：
- "9003:9003"（左边是宿主机端口，右边是容器内端口） - 如果用的是 Alpine 镜像且 PHP-FPM 模式，确保容器内确实在监听该端口（
netstat -tlnp | grep 9003） - Linux 下
host.docker.internal不可用，得用extra_hosts或直接填宿主机网关 IP（如172.17.0.1） - Mac/Windows Docker Desktop 可放心用
host.docker.internal，但别写成localhost——容器里的 localhost 是它自己
php.ini 或 xdebug.ini 中 client_host 和 mode 必须匹配运行环境
Xdebug 3 不再认 xdebug.remote_host，硬写进去会被忽略，还可能报 Unknown configuration setting。真正起效的是以下三者组合：
-
xdebug.mode=debug：不设这个，其他全白配；develop或off都不会发起调试连接 -
xdebug.start_with_request=yes或trigger：CLI 模式下必须用yes；Web 请求建议用trigger，靠?XDEBUG_SESSION_START=PHPSTORM或 Xdebug Helper 插件激活 -
xdebug.client_host=host.docker.internal（Mac/Win）或192.168.x.x（Linux 宿主机真实 IP）：别信网上教程写的127.0.0.1，那在容器里连的是自己
PhpStorm/VS Code 监听端口和 path mapping 缺一不可
IDE 界面显示“Listening”图标亮了，不代表真能收包——它只管本地端口是否空闲，不管 Xdebug 是否发来连接请求。
立即学习“PHP免费学习笔记（深入）”；
- PhpStorm：Settings → PHP → Debug → Xdebug →
Debug port必须是9003（不是默认的9000），且勾选Start listening for PHP Debug Connections - VS Code：确认
.vscode/launch.json中"port": 9003，且已切换到 Run and Debug 视图并点击绿色 ▶ 启动调试会话（不是按 F5） -
path mapping必须手动配：容器内路径（如/var/www/html）→ 本地项目根目录；不配就显示 “No executable code found” 或断点灰掉 - Linux 宿主机上，检查防火墙是否放行出站：
sudo ufw status或sudo iptables -L OUTPUT，重点看是否允许向你的开发机 IP:9003 发起连接
最常被忽略的是：Docker 容器里改了配置，但没重建或重载服务；或者 xdebug.log=/tmp/xdebug.log 开着却没去翻日志——里面一句 Connection to 'host.docker.internal:9003' failed 就能直接定位是 DNS 解析失败还是端口不通。
