Xdebug 3 在 Yii 中断点生效需同时满足四条件：PHP 加载 Xdebug 扩展、IDE 监听端口通畅、路径映射准确、请求触发调试会话；任一缺失均导致断点静默失败。
Xdebug 3 在 Yii 中能断点，前提是 PHP 进程加载了它、IDE 监听端口通、路径映射对、且请求触发了调试会话——缺一不可。很多“配好了却不停”的问题，其实卡在其中某一个环节。
确认 Xdebug 扩展已加载且版本匹配
先验证 PHP 是否真认得 Xdebug：php -m | grep xdebug 或 php --ini 找到生效的 php.ini，再运行 php -i | grep -A5 -B5 "xdebug"。若无输出或显示 xdebug => disabled，说明扩展没加载成功。
- Linux/macOS 常见路径是
/usr/lib/php/*/xdebug.so或/opt/homebrew/lib/php/pecl/*/xdebug.so；Windows 是php/ext/php_xdebug.dll - Xdebug 2 和 3 配置项不兼容：Xdebug 3 废弃了所有
xdebug.remote_*，必须用xdebug.mode=debug、xdebug.client_host、xdebug.client_port - 如果用 Docker，
docker exec -it查容器内状态，别只看宿主机php -m
php.ini 中最关键的几行配置
在 php.ini 末尾添加（或修改）以下内容，顺序不重要，但值必须准确：
zend_extension=xdebug.so xdebug.mode=debug xdebug.start_with_request=yes xdebug.client_host=127.0.0.1 xdebug.client_port=9003 xdebug.idekey=PHPSTORM
注意：
-
xdebug.client_port必须和 IDE 的监听端口一致；9000 很容易被php-fpm或其他服务占用，建议固定用9003 - Linux Docker 容器里
xdebug.client_host别写localhost，应设为host.docker.internal（Mac/Win）或通过--add-host指向宿主机网关 -
xdebug.idekey不强制，但如果 IDE 配了 DBGp Proxy，这个值要和 Proxy 的 IDE Key 严格一致
PhpStorm / IDEA 中服务器与路径映射必须对齐
进 Settings → PHP → Servers，填的不是本地 IP，而是你浏览器访问 Yii 应用时用的域名（比如 yii2.test），Host 字段填这个域名，Port 填 Web 服务端口（如 80 或 8080）。
关键一步在下面：
- 务必勾选
Use path mappings - 左边填容器内或服务器上的绝对路径（如
/var/www/html或/Users/xxx/yii2-app） - 右边填你本地项目根目录的绝对路径（和 IDE 打开的项目路径完全一致）
- 如果路径映射错位，断点会“看起来打了”，但永远不命中
触发调试会话的三种可靠方式
光有配置还不够，得让 Xdebug 主动连上来。最稳的方式是显式发起：
- 浏览器装
Xdebug Helper插件，点击虫子图标并选Debug，它会在请求头加XDEBUG_SESSION_START=PHPSTORM - Apifox / Postman 发请求时手动加 Cookie：
XDEBUG_SESSION=PHPSTORM - 直接在 URL 后加参数：
?XDEBUG_SESSION_START=PHPSTORM（需xdebug.start_with_request=trigger，但不如yes稳定）
别依赖 xdebug_break() 放在 index.php 开头——Yii 的自动加载或输出缓冲可能让它失效；断点打在控制器 action 方法里更可靠。
最容易被忽略的是路径映射和 xdebug.client_host 的宿主网络可达性。Docker 用户常以为配了 127.0.0.1 就行，其实容器里它指向自己；IDE 用户常把服务器 Host 填成 localhost，但实际访问用的是 yii2.test，导致映射失败。这些细节一错，整个调试链就静默断开。
