Yii2的Docker环境Xdebug配置_远程调试断点设置【攻略】

Xdebug远程调试需显式挂载xdebug.ini并正确配置：xdebug.mode=debug、xdebug.start_with_request=yes、xdebug.client_host设为host.docker.internal（linux需extra_hosts）、xdebug.client_port与phpstorm端口一致，且启用path mapping；Xdebug 3已废弃所有remote_*参数。

docker-compose.yml 里 xdebug 配置项必须显式挂载配置文件

yii2 在 Docker 中跑起来容易，但 Xdebug 远程调试连不上，八成是 xdebug.ini 没生效。Docker 官方 PHP 镜像（比如 php:8.1-apache）默认不加载 Xdebug，哪怕你 pecl install xdebug 了，没配好 ini 文件路径或加载顺序，phpinfo() 里照样看不到 xdebug 扩展。

• 必须用 volumes 把自定义的 xdebug.ini 挂载进容器，路径得对上 PHP 的配置目录（常见是 /usr/local/etc/php/conf.d/）
• 不要依赖 Dockerfile 里 RUN echo "..." > /usr/local/etc/php/conf.d/xdebug.ini —— 构建镜像后改配置还得重构建，调试时根本来不及
• xdebug.mode=debug 和 xdebug.start_with_request=yes 是最低要求，少一个断点就触发不了
• xdebug.client_host 别写 localhost：Docker 容器里 localhost 指自己，得换成宿主机网关，Mac/windows 用 host.docker.internal，Linux 得手动加 --add-host=host.docker.internal:host-gateway

services:   php:     image: php:8.1-apache     volumes:       - ./xdebug.ini:/usr/local/etc/php/conf.d/docker-xdebug.ini     extra_hosts:       - "host.docker.internal:host-gateway"

PHPStorm 的 DBGp Proxy 设置必须和 Yii2 容器名对齐

Xdebug 3 要求 ide 做“代理”角色，尤其当多个 PHP 容器（比如 api + admin）共用一个 IDE 时，DBGp Proxy 不配，断点会静默失败，控制台也没报错。

• 进入 Settings → PHP → Servers，填的 Host 是你访问 Yii2 的域名（比如 yii2.test），不是 localhost
• Debugger port 必须和 xdebug.client_port 一致（默认 9003）
• 关键一步：勾选 Use path mappings，然后把容器内路径（如 /var/www/html）映射到本地 Yii2 项目根目录
• 如果用了多容器，DBGp Proxy 的 IDE key 要设成和 xdebug.idekey 一样（比如 PHPSTORM），且 Host 填的是运行 PHPStorm 的机器 IP（不是 localhost）

Yii2 的 index.php 入口必须触发 Xdebug 启动逻辑

有些同学在 index.php 开头加了 xdebug_break()，结果断点还是不进 —— 因为 Yii2 的自动加载机制可能让 Xdebug 在入口前就退出了，或者被 ob_start() 类函数干扰。

• 最稳的方式是靠 URL 参数触发：<a href="https://www.php.cn/link/11aa6498304a996e1efc6720e1a1a630">https://www.php.cn/link/11aa6498304a996e1efc6720e1a1a630</a>，前提是 xdebug.start_with_request=trigger
• 不推荐在 index.php 里硬写 xdebug_break()，它只在脚本执行到那行才起作用，而 Yii2 的 require <strong>DIR</strong> . '/vendor/autoload.php' 可能已经初始化了部分类，断点位置偏移
• 如果用 nginx，确认没开启 fastcgi_buffering off 之类影响调试流的配置；Apache 用户注意 mod_php 和 php-fpm 下 xdebug 加载方式不同，Docker 环境基本都是 fpm 模式

Xdebug 3 升级后 xdebug.remote_* 全部失效

从 Xdebug 2 升到 3 是最大坑点。所有带 remote_ 的旧参数（xdebug.remote_enable、xdebug.remote_host 等）已被移除，继续写进去不仅无效，还会让整个扩展加载失败。

• 替换对照表必须记牢：xdebug.remote_enable → xdebug.mode=debug，xdebug.remote_host → xdebug.client_host，xdebug.remote_port → xdebug.client_port
• xdebug.mode 是复合值，支持逗号分隔：debug,develop 表示启用调试 + 开发辅助（比如超全局变量显示）
• xdebug.log 路径要容器内可写（比如 /tmp/xdebug.log），日志里第一行就告诉你哪些配置被忽略或格式错误，比猜强得多

最常被跳过的其实是容器网络层——client_host 写错、extra_hosts 漏加、IDE 监听端口被防火墙拦住，这三处任一出问题，Xdebug 就安静得像没装过。调不通时先看 /tmp/xdebug.log，别急着改 Yii2 代码。