PhpStorm在Docker中断点不触发，90%因xdebug.client_host错误或端口不通；须删尽xdebug.remote_*旧参数，仅留xdebug.mode=debug、xdebug.start_with_request=trigger、xdebug.client_host=host.docker.internal（Linux需换宿主机IP），并确保PHPStorm监听开启、路径映射精准、端口9003未被占用且防火墙放行。
PhpStorm 在 Docker 环境下断点不触发，90% 是 xdebug.client_host 指向错误或端口未连通，不是代码或 IDE 设置本身的问题。
确认 Xdebug 3.x 配置是否混用旧参数
Xdebug 3.x 完全废弃 xdebug.remote_* 系列配置（如 xdebug.remote_host、xdebug.remote_port），若残留这些项，会导致 xdebug.mode=debug 静默失效——phpinfo() 显示已加载，但断点完全不响应。
- 删掉 php.ini 或
xdebug.ini中所有以xdebug.remote_开头的行 - 只保留三行核心配置（Docker 容器内）：
xdebug.mode=debug xdebug.start_with_request=trigger xdebug.client_host=host.docker.internal
-
xdebug.client_port必须与 PhpStorm 中 Settings → PHP → Debug → Debug port 值一致（默认9003） - 重启 PHP-FPM 或容器：
docker exec -it <container> kill -USR2 1或docker restart
验证 host.docker.internal 是否可解析
该 DNS 名在 Docker Desktop（Windows/macOS）中自动注入，但在 Linux 原生 Docker 或某些 CI 环境中并不存在，直接导致 Xdebug 连接失败，日志里出现 Connection to 'host.docker.internal:9003' failed。
- 进容器执行：
ping -c 1 host.docker.internal，不通则需手动指定宿主机 IP - 查宿主机 IP（Linux/macOS）：
ip route | awk '{print $3}' | head -n1；Windows WSL2 可用cat /etc/resolv.conf | grep nameserver | awk '{print $2}' - 将
xdebug.client_host改为查到的 IP，例如xdebug.client_host=172.17.0.1 - 若使用
docker-compose.yml，可在服务中加extra_hosts显式注入：extra_hosts: - "host.docker.internal:host-gateway"
检查 PhpStorm 监听状态和路径映射
断点“画上了”但不中断，大概率是 PhpStorm 找不到对应文件——路径映射错位，或监听根本没开。
立即学习“PHP免费学习笔记（深入）”；
- 必须手动启用监听：Run → Start Listening for PHP Debug Connections（右下角显示
Debug listening…） - Settings → PHP → Servers 中添加服务器，Host 填你访问项目的域名（如
localhost或app.test），Port 填 Web 服务端口（如80或8000） - 务必勾选
Use path mappings，并严格匹配：
Local path（你的项目根目录，如/Users/name/project）→
Deployment path（容器内绝对路径，如/var/www/html） - 测试映射是否生效：在 PhpStorm 中右键任意 PHP 文件 →
Copy Relative Path，看是否与容器内路径结构一致
排查连接被拦截或端口冲突
即使配置全对，Connection refused 错误仍常见于防火墙、IDE 权限或端口占用。
- 检查 PhpStorm 是否允许外部连接：Settings → PHP → Debug → 勾选
Can accept external connections - 确认端口未被占用：
lsof -i :9003（macOS/Linux）或netstat -ano | findstr :9003（Windows） - 若用 WSL2，确保 Windows 防火墙放行
9003端口，且 PhpStorm 运行在 Windows 侧（非 WSL 内） - 临时关闭杀毒软件或安全工具，某些国产软件会静默拦截 DBGp 连接
- 查看 Xdebug 日志：
xdebug.log路径设在容器内可写位置，日志末尾出现Connected to client才算真正打通
最易被忽略的是：Xdebug 3.x 默认不监听 CLI 请求，Web 调试必须通过浏览器访问 URL 触发；用 php script.php 运行脚本不会启动调试通道，除非显式加 -dxdebug.mode=debug。
