Xdebug调试失败90%是php.ini与PhpStorm的端口、idekey、路径映射三者不一致所致；须先确认xdebug扩展已加载（php -m | grep xdebug），再严格对齐xdebug.client_port=9003、xdebug.idekey=PHPSTORM及Servers中路径映射，缺一不可。
直接说结论：Xdebug 调试失败，90% 是 php.ini 和 PhpStorm 端口、idekey、路径映射三者不一致导致的，不是版本不兼容，也不是插件没装——先对齐这三项，再谈其他。
确认 Xdebug 扩展已正确加载
别跳过这步。很多人以为改完 php.ini 就行了，其实扩展根本没加载成功。
- 新建
info.php，内容为<?php phpinfo(); ?>，用浏览器访问，搜索页面里有没有 Xdebug 区块（不是只看“xdebug”字样，要找完整模块标题） - 命令行执行
php -m | findstr xdebug（Windows）或php -m | grep xdebug（macOS/Linux），有输出才说明扩展已启用 - 如果没出现，检查
zend_extension路径是否拼写错误、文件是否存在、DLL/SO 是否与 PHP 架构（TS/NTS、x86/x64）和 VC 版本（vc15/vc17）严格匹配
php.ini 中必须设置的几项（Xdebug 3.x）
Xdebug 3.x 配置项和 2.x 完全不同，混用必失败。以下是最小必要配置（PHP 7.4+ / 8.x 推荐）：
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.remote_* 系列（如 xdebug.remote_enable）在 Xdebug 3 中已废弃，继续写会静默失效；xdebug.client_port 必须和 PhpStorm 中 Debug Port 严格一致；xdebug.idekey 值必须和 PhpStorm 的 DBGp Proxy 设置完全相同（大小写敏感）。
立即学习“PHP免费学习笔记（深入）”；
PhpStorm 的关键三项配置
Settings → Languages & Frameworks → PHP → Debug：
-
Debug Port：填入和xdebug.client_port相同的值（如9003），不要用默认9000（常被 Docker 或其他服务占用） - Settings → Languages & Frameworks → PHP → Servers：添加一个 Server，
Host填你实际访问项目的域名（如localhost或test.local），Port填 Web 服务器端口（如80或8080），勾选Use path mappings，并在下方映射本地项目根目录到服务器绝对路径（例如D:\project\src → /var/www/html） - Settings → PHP → Debug → DBGp Proxy：
IDE key必须等于php.ini中的xdebug.idekey（如PHPSTORM），Host填127.0.0.1，Port填和上面相同的9003
启动调试前最容易漏掉的两件事
即使配置全对，缺这两步也进不了断点：
- PhpStorm 右上角那个电话图标（
Start Listening for PHP Debug Connections）必须是绿色波纹状态，不是灰色或红色 - 浏览器请求必须携带调试触发标识 —— 最可靠方式是安装
Xdebug Helper插件（Chrome/Firefox 均有），右键插件图标 →Debug，此时地址栏 URL 末尾会自动追加?XDEBUG_SESSION_START=PHPSTORM；不用插件的话，手动加这个参数也行，但 Cookie 方式（XDEBUG_SESSION）容易残留旧值，建议每次调试前清空 Cookie
路径映射不对会导致「File path is not mapped」警告，断点灰掉无法命中；端口不一致则 PhpStorm 根本收不到连接请求，监听图标也不会变绿——这两个问题没有中间态，非黑即白，优先排查。
