应将 xdebug 3 的 xdebug.client_host 设为 docker.for.mac.localhost，因其自动解析宿主机实时 ip，避免手动 ip 失效；同时确保 phpstorm 监听 9003 端口、启用远程连接并放行防火墙。
为什么 127.0.0.1 在 Docker for Mac 里连不上宿主机的 PhpStorm？
因为容器里的 127.0.0.1 指向的是容器自己，不是你的 Mac。你本地跑着 PhpStorm 监听 9003 端口（Xdebug 3 默认），但容器发请求时根本没发到 Mac 上——它卡在自己内部了。
常见错误现象包括：xdebug.log 里完全没连接记录、PhpStorm 右下角不弹 “Incoming connection…”、断点永远灰掉。
- 别再硬写宿主机局域网 IP（如
192.168.1.144）：Wi-Fi 切换、热点共享后就失效 - 别用
--network host：Mac 不支持该模式，会直接报错 - Xdebug 2 和 Xdebug 3 的配置项名完全不同，混用会导致扩展加载失败或静默忽略
xdebug.client_host 必须设为 docker.for.mac.localhost
这是 Docker Desktop for Mac 提供的内置 DNS 名称，会自动解析成当前宿主机的实时 IP，且无需手动维护。它专为这类场景设计，比任何手动 IP 或脚本更可靠。
对应配置（Xdebug 3）：
zend_extension=xdebug.so xdebug.mode=debug xdebug.client_host=docker.for.mac.localhost xdebug.client_port=9003 xdebug.idekey=PHPSTORM xdebug.start_with_request=yes xdebug.log=/tmp/xdebug.log
-
xdebug.client_host是 Xdebug 3 的关键项，xdebug.remote_host（Xdebug 2）已废弃，设了也无效 - 端口必须和 PhpStorm 中 “Settings > PHP > Debug > Xdebug” 里的
Debug port一致，默认是9003，不是9000 -
xdebug.start_with_request=yes表示每次 HTTP 请求都尝试连接，适合开发；若只想按需触发，改用trigger模式并加?XDEBUG_SESSION_START=PHPSTORM参数
PhpStorm 必须监听 9003 且允许外部连接
即使 Xdebug 配置全对，PhpStorm 如果没开监听或被系统防火墙拦住，照样收不到请求。
- 进
Preferences > PHP > Servers，确认服务器 Host 填的是localhost或docker.for.mac.localhost，不是容器内域名 - 进
Preferences > PHP > Debug > Xdebug，勾选Accept remote connections，端口填9003 - macOS 自带防火墙默认会拦截非签名应用的入站连接，进“系统设置 > 网络 > 防火墙 > 防火墙选项”，把 PhpStorm 加入“允许传入连接的应用程序”列表
- 不要依赖
phpstorm://协议跳转：它只负责打开 IDE，不保证调试通道畅通；真正靠的是 socket 连接是否建立
验证连接是否真的通了
光看日志不够，得从容器里主动 ping 和 telnet 宿主机调试端口，才能定位是网络层还是应用层问题。
- 进容器执行：
ping -c 3 docker.for.mac.localhost—— 应返回真实 IP 并通 - 再执行：
nc -zv docker.for.mac.localhost 9003—— 应显示succeeded!；如果超时，说明 PhpStorm 没监听或被防火墙挡了 - 检查
/tmp/xdebug.log末尾是否有类似[Step Debug] Could not connect to debugging client，有则说明 Xdebug 发出了请求但没人应答 - 重启容器后，务必重新加载一次页面（或发个 cURL 请求），Xdebug 不会在后台常驻连接
最易被忽略的一点：Xdebug 3 的 xdebug.mode 是必填项，空值或错值会导致整个调试模块不激活，且无任何提示——它就安静地当个普通扩展。
