xdebug远程调试连不上90%是配置未生效或网络路径错误：需显式挂载xdebug.ini、正确设置xdebug.client_host（如host.docker.internal）、配准pathmappings，并开启xdebug.log定位问题。
xdebug 远程调试连不上，90% 是配置没生效或网络路径不通——不是装得不对，是容器里根本没加载你写的 xdebug.ini，或者 xdebug.client_host 指错了地方。
xdebug.ini 必须显式挂载，不能靠 RUN echo 写进镜像
Docker 官方 PHP 镜像（如 php:8.2-apache）默认不带 xdebug，哪怕你 pecl install xdebug 了，没把配置文件正确加载进 PHP 的 conf.d/ 目录，phpinfo() 就不会显示它。
-
docker-compose.yml中必须用volumes显式挂载：./xdebug.ini:/usr/local/etc/php/conf.d/docker-xdebug.ini
- 路径必须对：PHP 会按字母顺序加载
/usr/local/etc/php/conf.d/*.ini，文件名建议带前缀（如docker-xdebug.ini），避免被其他 ini 覆盖 - 别在
Dockerfile里用RUN echo "xdebug.mode=debug" > /usr/local/etc/php/conf.d/xdebug.ini—— 构建完就固化了，改个端口就得重构建，调试时根本来不及
xdebug.client_host 不能写 localhost
容器里的 localhost 指的是自己，不是你的宿主机。Xdebug 要连的是你本地 IDE（比如 PhpStorm），所以这个值必须指向宿主机的网关：
Docker Image Puller
下载
使用 Python 脚本下载 Docker 镜像并打包为 tar 文件。用户说“下载镜像”“拉取镜像”“pull xxx”“帮我下载 nginx 镜像”等时触发。支持 SOCKS5 代理直连（推荐）和国内镜像站加速两种模式。
- macOS / Windows（Docker Desktop）：直接写
host.docker.internal - Linux：Docker 默认不提供这个域名，得在
docker-compose.yml里加：extra_hosts: - "host.docker.internal:host-gateway"
- 别手贱填
127.0.0.1或172.17.0.1—— 前者在容器里连不到宿主机端口，后者是 Docker 网桥地址，不一定通且不稳定
PHPStorm 的 path mapping 和 DBGp Proxy 容易漏配
断点不触发，经常不是 Xdebug 没连上，而是 IDE 根本不知道“容器里的 /var/www/html”对应你本地哪条路。
- 进入
Settings → PHP → Servers：-
Host填你访问应用的域名（如yii2.test），不是localhost - 勾选
Use path mappings - 把
/var/www/html映射到你本地项目根目录（如/Users/me/yii2）
-
- 多容器场景（比如
api+admin共用一个 PhpStorm）：- 必须启用
DBGp Proxy -
IDE key要和xdebug.idekey一致（如PHPSTORM） -
Host填宿主机真实 IP（比如192.168.1.105），不能填localhost，否则代理收不到请求
- 必须启用
xdebug.log 是唯一能告诉你“卡在哪”的证据
光看 IDE 界面 “Waiting for incoming connection…” 没用，打开日志才能定位真实问题：
- 在
xdebug.ini加两行：xdebug.log=/tmp/xdebug.log xdebug.log_level=7
- 进容器查日志：
tail -f /tmp/xdebug.log - 常见线索：
-
Could not connect to client→client_host或防火墙问题 -
Invalid ide key→xdebug.idekey和 PhpStorm 设置不一致 - 日志完全空白 →
xdebug.ini根本没加载，或xdebug.mode没设成debug
-
最常被忽略的，是以为配完就能断点，结果连日志都不开——等半天没反应，不如先 cat /tmp/xdebug.log 看一眼。
