Xdebug调试连不上主因是php.ini路径错配、端口不一致或PhpStorm未加载目标配置文件；须统一CLI与Web环境的php.ini路径，严格匹配xdebug.client_port与PhpStorm Debug port，并确保xdebug.mode=debug等Xdebug 3参数正确启用。
调试连不上，八成不是 Xdebug 没装，而是 php.ini 没改对、端口不一致、或 PhpStorm 用的不是你认为的那个 PHP 配置文件。
确认 PHP 加载的是你改的 php.ini
很多人改了 php.ini 却没生效，是因为 CLI（命令行）和 Web（浏览器）加载的是两份不同配置。必须让两者指向同一份文件。
- 在 PhpStorm 中打开 Settings > Languages & Frameworks > PHP，点开 CLI 解释器右侧的“…” → 查看
Configuration file路径 —— 这是你必须编辑的那份 - 另起一个
test.php文件，写入<?php phpinfo(); ?>，在浏览器中访问它，搜索 Loaded Configuration File，确认路径和上面完全一致 - 如果不一致：要么把 Web 服务器（如 Apache/Nginx）的配置指向 CLI 的
php.ini，要么统一用 phpStudy/XAMPP 等集成环境，避免多份配置共存
xdebug.mode=debug 是 Xdebug 3 的开关，不是可选项
Xdebug 3.x（2021 年后新装基本都是）彻底废弃了 xdebug.remote_enable 等旧参数。混用会导致静默失败：断点不触发、无报错、日志也为空。
- 必须启用的最小配置（写在
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
zend_extension 路径必须精确：Linux/macOS 用 .so，Windows 用 .dll，且不能带注释或空格xdebug.idekey 和 PhpStorm 的 Settings > PHP > Debug > DBGp Proxy > IDE key 必须完全一致（区分大小写）9003 要和 PhpStorm 的 Settings > PHP > Debug > Debug port 数值严格匹配浏览器怎么“喊”PHP 开始调试？
PhpStorm 点了「开始监听」≠ PHP 就自动调试。PHP 必须收到明确信号，否则请求直接走完，根本不会连 IDE。
立即学习“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、WSL 或某些路由器环境下，它可能把调试请求发到错误 IP，坚持用client_host
断点不命中？先看这三处日志
没日志就等于蒙眼调，Xdebug 的失败几乎从不报错，只沉默跳过。
- 在
php.ini加一行：xdebug.log=/tmp/xdebug.log（Linux/macOS）或xdebug.log=C:\temp\xdebug.log（Windows），重启服务后触发一次请求，看日志里有没有Connection refused或Could not connect to client - PhpStorm 右下角状态栏点「Debug」→ 查看是否显示
Listening for Xdebug connections...；如果没显示，说明监听根本没启动 - 路径映射错一个字符就会失败：在 Settings > PHP > Servers 中，确保「Project root」映射到「Web server root URL」下的对应路径（例如本地项目
/home/user/project映射到http://localhost/的/）
最常被忽略的其实是路径映射和 php.ini 加载路径的双重验证 —— 其他配置全对，这两处差一点，调试就永远卡在“已监听，但没连接”。
