xdebug调试需确保php加载正确php.ini、配置项与xdebug版本匹配、端口及ide key一致、路径映射准确，并开启日志排查；xdebug 3.x必须用xdebug.mode=debug等新参数，且zend_extension路径须精确无误。
直接说结论：Xdebug 调试不是“装上就能用”，xdebug.remote_enable=1 和 zend_extension 路径写对只是起点，真正卡住人的往往是端口不一致、IDE key 不匹配、或 PHP 解释器没指向正确的 php.ini。
确认 PHP 正在加载你改的 php.ini
很多人改了 php.ini 却没生效，是因为 PHPStorm 用的 CLI 解释器和 Web 服务器（如 Apache/Nginx）加载的不是同一个配置文件。
- 在 PHPStorm 中打开 Settings > Languages & Frameworks > PHP，点击 CLI 解释器旁的
...，查看「Configuration file」路径 —— 这才是你要改的那个php.ini - 同时，在浏览器中访问一个含
<?php phpinfo(); ?>的页面，搜索Loaded Configuration File，确认 Web 环境加载的是不是同一份 - 两个环境必须用同一份
php.ini，否则断点只在 CLI 有效（或反之），调试永远连不上
关键配置项不能漏、不能错
Xdebug 3.x 和 2.x 的配置项名差异很大，混用会导致完全静默失效（无报错、无日志、断点不触发）。
- 如果你用的是 Xdebug 3.0+（2021 年后新装大概率是），必须用：
xdebug.mode=debug，而不是xdebug.remote_enable=1 -
xdebug.start_with_request=yes替代旧版的xdebug.remote_autostart=1；xdebug.client_host=127.0.0.1替代xdebug.remote_host -
xdebug.idekey=PHPSTORM必须和 PHPStorm 的 Debug > DBGp Proxy > IDE key 完全一致（区分大小写） -
xdebug.client_port=9003（Xdebug 3 默认端口）要和 PHPStorm 的 Debug > Debug Port 数值完全相同
浏览器怎么通知 PHP 启动调试？
不是点了「开始监听」就自动调试，PHP 需要明确收到「现在要调试」的信号。
- 最稳妥的方式：在 URL 末尾加
?XDEBUG_SESSION_START=PHPSTORM（注意值必须和xdebug.idekey一致） - 用 Chrome 插件
Xdebug Helper时，右键图标 →「Debug」，它会自动在请求头里加 Cookie：XDEBUG_SESSION=PHPSTORM - 如果开了
xdebug.start_with_request=yes，那每次请求都会尝试连接，但仅当 PHPStorm 处于「监听」状态时才真正建立调试会话 - 别依赖
xdebug.remote_connect_back=1，它在 Docker 或某些 NAT 网络下会把请求发到错误 IP，优先用xdebug.client_host
断点不命中？先看这三处日志
没有日志，等于瞎调。Xdebug 的静默失败往往是因为路径映射没配对，或者监听根本没启动。
- 开启 Xdebug 日志：
xdebug.log="/tmp/xdebug.log"（Linux/macOS）或xdebug.log="C:\temp\xdebug.log"（Windows），重启 PHP 后看是否有「connection established」或「Connection refused」 - PHPStorm 右下角有「Debug」小图标，鼠标悬停能看到当前监听状态和端口；如果显示「Not listening」，说明按钮没点下去
- 首次连接时，PHPStorm 会弹出
Configure Path Mapping对话框——这里填的「Web server root URL」和「Project files」必须严格对应，比如你的项目在D:projectpi，而浏览器访问的是http://localhost/api/index.php，那映射就必须是/api → D:projectpi
最容易被忽略的是：Xdebug 3 默认关闭所有功能，只开 debug 模式还不够，如果还用了 profiling 或 trace，得显式加上 xdebug.mode=debug,profile；另外，zend_extension 路径里的 DLL/SO 文件名一旦拼错半个字符，PHP 就会静默跳过加载，连警告都不报。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
