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 代码。
