host.docker.internal是docker提供的特殊dns名，用于容器访问宿主机；macos/windows默认支持，linux需通过--add-host host.docker.internal:host-gateway启用，alpine镜像需注意dns配置。
host.docker.internal 是 Docker 提供的一个特殊 DNS 名，用于让容器内服务快速访问宿主机。但它并非在所有平台原生可用——这个细节恰恰是 Xdebug 调试连不上最常被忽略的根源之一。
host.docker.internal 的平台差异必须清楚
-
macOS / Windows（Docker Desktop）：默认启用，可直接在
xdebug.client_host=host.docker.internal中使用，解析为宿主机网关 IP -
Linux（原生 Docker）：默认不支持，容器内
ping host.docker.internal会失败，Xdebug 就卡在连接阶段 -
Alpine Linux 镜像：即使在 macOS/Windows 上运行，若基础镜像是 Alpine，仍需确保
host.docker.internal能被正确解析（通常没问题，但要注意 DNS 配置）
Linux 下替代 host.docker.internal 的可靠方案
不要硬写宿主机 IP（比如 172.17.0.1），因为桥接网络网关可能随 Docker 重启或网络重置而变化。推荐两种稳定做法：
- 启动容器时加参数：
docker run --add-host=host.docker.internal:host-gateway ...
- 或在
docker-compose.yml中为对应服务添加：extra_hosts: - "host.docker.internal:host-gateway"
✅
host-gateway是 Docker 20.10+ 引入的保留词，会自动映射为宿主机在当前 Docker 网络中的真实 IP，比手动查ip route | awk '{print }'更健壮。
多项目、多域名场景下的注意事项
当你有多个 PHP 项目（如 api.test、admin.test）共用一个调试环境时：
- 所有项目容器都应配置相同的
extra_hosts（或--add-host） -
xdebug.client_host统一设为host.docker.internal，无需按域名区分 - 真正区分调试会话的是
xdebug.idekey和路径映射（path mapping），不是 client_host
验证是否生效的小技巧
进容器执行：
getent hosts host.docker.internal
如果返回一个 IPv4 地址（如 172.17.0.1），说明解析成功；
如果无输出或报错，则 xdebug.client_host 实际指向空，断点必然不触发。
Xdebug 的 client_host 不是“可选字段”，而是建立调试连接的第一跳地址。设错它，后面所有配置都白搭。
