解决PhpStorm在Docker环境下无法调试断点的问题-phpstorm-PHP中文网

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环境下无法调试断点的问题

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</container> 或 docker restart

验证 `host.docker.internal` 是否可解析

该 DNS 名在 Docker Desktop（Windows/macOS）中自动注入，但在 Linux 原生 Docker 或某些 CI 环境中并不存在，直接导致 Xdebug 连接失败，日志里出现 Connection to 'host.docker.internal:9003' failed。

Docker Compose Linter

检查 docker-compose.yml 文件的安全问题、最佳实践和端口冲突

下载

进容器执行：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 找不到对应文件——路径映射错位，或监听根本没开。

必须手动启用监听：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 才算真正打通