PhpStorm与Xdebug联调失败主因是xdebug.mode和php.ini端口/主机配置未对齐，或PhpStorm未识别PHP解释器中的Xdebug扩展；须删尽xdebug.remote_*旧参数，仅保留zend_extension=xdebug、xdebug.mode=debug、xdebug.client_host、xdebug.client_port、xdebug.start_with_request，并确保php -m | grep xdebug有输出且PhpStorm解释器路径与Debug端口严格匹配。
PhpStorm 与 Xdebug 联调失败，90% 是因为 xdebug.mode 和 php.ini 中的端口/主机配置没对齐，或 PhpStorm 没识别到 PHP 解释器里的 Xdebug 扩展。Xdebug 3.x 后配置逻辑已变，沿用旧教程（比如设 xdebug.remote_enable）必然失败。
确认 Xdebug 是否真正加载并匹配 PHP 版本
别只看 phpinfo() 页面有没有 “xdebug” 字样——那只是扩展名显示，不等于它被正确启用。必须验证实际加载状态：
- 终端执行
php -v，输出里必须含with Xdebug v3.x.x（不是with Zend OPcache那种附带信息） - 执行
php --ini确认生效的php.ini路径，然后打开它，在末尾添加（Xdebug 3.3+ 推荐写法）：zend_extension=xdebug<br>xdebug.mode=debug<br>xdebug.client_host=127.0.0.1<br>xdebug.client_port=9003<br>xdebug.start_with_request=yes
- 删掉所有
xdebug.remote_*开头的旧配置（Xdebug 3 已废弃），否则会静默忽略 - 重启 PHP-FPM 或 Apache/Nginx，再运行
php -m | grep xdebug，有输出才表示扩展真正载入
PhpStorm 必须正确识别 PHP 解释器和 Debug 端口
即使 php -m 显示 xdebug，PhpStorm 若用错解释器路径，仍无法建立调试通道。关键点在 Settings → PHP 节点下两处：
- PHP Language level 和 Interpreter 必须指向你刚验证过的那个
php可执行文件（如/usr/bin/php或C:\php\php.exe），不是系统默认的旧版本 - Settings → PHP → Debug → Xdebug → Debug Port 必须严格等于
php.ini中的xdebug.client_port（默认 9003），不能是 9000（那是 Xdebug 2 的默认值） - 取消勾选
Force break at first line...，除非你真需要每次进脚本都停在第一行 - 如果本地开发用 Docker 或 WSL，
xdebug.client_host要填宿主机 IP（如10.0.2.2），而非127.0.0.1
路径映射（Path Mapping）是远程/虚拟环境调试成败关键
当项目在 Docker、Vagrant 或远程服务器上运行时，PhpStorm 看到的文件路径（如 /var/www/html/index.php）和本地项目路径（如 /Users/me/project/index.php）不一致，断点会失效。必须配准：
立即学习“PHP免费学习笔记（深入）”；
- Settings → PHP → Servers，新增或编辑对应服务器（Name 填任意，Host 填访问域名如
localhost，Port 填 Web 端口如80） - 勾选
Use path mappings，点击右侧...，添加映射：
– Local path：你本地项目根目录（绝对路径）
– Absolute path on the server：容器或服务器内对应的完整路径（如/var/www/html） - 映射必须精确到目录层级，不能漏掉末尾斜杠，也不能多一层
./ - 若用 phpStudy、XAMPP 等集成环境，路径映射通常可跳过；但只要涉及非本地直连，就必须检查此项
触发调试的两种方式及常见卡点
监听开启后，得让请求“带上调试指令”，否则 Xdebug 不会主动拨号给 PhpStorm：
- 推荐方式：装 Chrome 插件 Xdebug Helper，右键图标 → Options → IDE Key 选
PHPSTORM，Domain Filter 填localhost或你的开发域名；之后点图标 → Debug，刷新页面即可 - 手动方式：在 URL 后加
?XDEBUG_SESSION_START=PHPSTORM（注意大小写，且PHPSTORM必须和php.ini中的xdebug.idekey一致；Xdebug 3 默认值为PHPSTORM，无需显式配置） - 常见卡点：
– 浏览器地址栏没变绿（插件未激活）
– PhpStorm 右上角电话图标是灰色/红色（没点开监听）
– 断点变成空心圆（表示未映射成功，鼠标悬停提示 “no executable code found”）
– 控制台报Connection refused（端口冲突或xdebug.client_host填错）
最易被忽略的是：Xdebug 3 默认关闭 xdebug.log，出问题时建议临时加上 xdebug.log=/tmp/xdebug.log（Linux/macOS）或 xdebug.log=C:\tmp\xdebug.log（Windows），日志里会明确写出连接尝试、拒绝原因和协议错误，比盲调快十倍。
