macOS下Docker容器无法连接主机9003端口求助

1. 确认PhpStorm的监听绑定范围 #

虽然lsof -nP -iTCP -sTCP:LISTEN显示TCP *:9003 (LISTEN)，但部分场景下PhpStorm可能实际仅绑定127.0.0.1（而非允许所有IP的0.0.0.0）：

• 打开PhpStorm的「Settings/Preferences」→「Languages & Frameworks」→「PHP」→「Debug」，确保「Allow incoming connections」已勾选
• 若仍有问题，可强制修改监听地址：编辑PhpStorm.app/Contents/bin/idea.properties，添加idea.xdebug.listen.address=0.0.0.0，重启PhpStorm
• 用netstat -an | grep LISTEN | grep 9003再次验证，输出需包含*.9003而非仅127.0.0.1.9003

2. 绕过host.docker.internal直接用主机IP测试 #

Docker的host.docker.internal解析可能存在异常，直接使用主机的局域网IP测试：

• 在macOS主机执行ifconfig en0（或对应网卡，如en1）获取inet字段的IP地址（比如192.168.1.100）
• 在容器内执行nc -vz 192.168.1.100 9003，如果能连通，说明host.docker.internal解析有问题，可在容器内的Xdebug配置中直接指定该IP作为xdebug.client_host

3. 排查macOS底层网络拦截 #

• 检查pfctl防火墙规则：执行sudo pfctl -s rules，查看是否存在针对9003端口的拒绝规则，临时关闭测试：sudo pfctl -d
• 确认macOS的「安全与隐私」→「防火墙」已完全关闭（不仅是允许PhpStorm，直接关闭防火墙验证）

4. 验证容器内Xdebug配置正确性 #

确保容器内的php.ini（或xdebug.ini）配置正确：

xdebug.mode = debug
xdebug.client_host = host.docker.internal  # 或主机局域网IP
xdebug.client_port = 9003
xdebug.start_with_request = yes
xdebug.log_level = 7  # 开启日志便于排查连接报错

• 开启Xdebug日志后，执行PHP脚本，查看容器内的Xdebug日志（默认路径/var/log/xdebug.log），定位连接超时、拒绝的具体原因

5. 重置Docker网络与相关服务 #

• 重启Docker Desktop：点击菜单栏Docker图标→「Restart」
• 重启PhpStorm，必要时清除缓存（「File」→「Invalidate Caches...」→「Invalidate and Restart」）
• 重置Docker网络：执行docker network prune，重新创建容器使用的网络

内容的提问来源于stack exchange，提问作者Oleksandr Savchenko