CLI 与 Web 环境 php.ini 路径不一致导致调试断连；需统一配置文件、校验 zend_extension 路径、正确设置路径映射及 xdebug.client_host/client_port。
php --ini 和 phpinfo() 显示的 Loaded Configuration File 不一致
这说明 CLI 和 Web 环境根本没用同一份 php.ini，调试必然断连。PhpStorm 的 CLI 解释器读的是 php --ini 输出的 Loaded Configuration File；而浏览器访问 phpinfo() 页面时，Apache/Nginx 加载的是另一个路径下的配置文件。
必须让两者指向同一个文件，否则你改了 Web 端的 xdebug.mode = debug，CLI 端却没生效，或者反之。常见于 WAMP/XAMPP 用户：Web 用的是 C:wamp64inphpphp8.3.14php.ini，但 PhpStorm 默认调用系统 PATH 下的 PHP（可能是旧版或独立安装），加载的是 C:phpphp.ini。
- 在终端运行
php --ini，记下Loaded Configuration File路径 - 新建
info.php，内容为<?php phpinfo(); ?>，用浏览器访问，搜索Loaded Configuration File - 如果两个路径不同，统一修改为其中一份（推荐用 Web 环境那份，因调试多走 HTTP 请求）
- 修改 PhpStorm 的 CLI 解释器：Settings → Languages & Frameworks → PHP → CLI Interpreter → 点击右侧
⋯→ 选择正确的php.exe（它会自动关联同目录下的php.ini）
php.ini 中写了 xdebug.mode=debug，但 phpinfo() 不显示 Xdebug 模块
不是配置没写对，而是 zend_extension 路径错了，或扩展根本没加载成功。Xdebug 3.x 强制要求使用 zend_extension，且路径必须精确到文件名（Windows 是 php_xdebug.dll，Linux/macOS 是 xdebug.so），不能只写目录。
典型错误包括：zend_extension = xdebug（缺后缀）、zend_extension = C:
mppphpextphp_xdebug（漏了 .dll）、路径含中文或空格未加引号、DLL 文件实际不存在于该路径。
立即学习“PHP免费学习笔记（深入）”；
- 检查
phpinfo()页面是否出现Xdebug大标题区块；没有就说明扩展未加载 - 确认
zend_extension行末尾无分号，路径用双引号包裹（尤其 Windows 路径含空格时） - Windows 下路径必须用正斜杠
/或双反斜杠\，单反斜杠会被解析为转义符 - 用
php -m | findstr xdebug（Windows）或php -m | grep xdebug（macOS/Linux）快速验证 CLI 是否加载
断点不触发，但 PhpStorm 已监听且 Xdebug 日志显示已连接
连接成功 ≠ 断点命中。最常被忽略的是路径映射（Path Mapping）——Xdebug 告诉 PhpStorm “我在执行 E:wwwpublicindex.php”，但 PhpStorm 本地打开的是 E:/www/public/index.php，它找不到对应文件，于是跳过断点。
Windows 用户尤其容易踩坑：PHP 报出的路径是 E:wwwpublicindex.php，而 PhpStorm 默认把本地路径识别为 E:/www/public/index.php，两者看似一样，实则协议不匹配（ vs /），导致映射失败。
- 打开 Settings → Languages & Frameworks → PHP → Servers，选中你的服务器
- 勾选
Use path mappings，左侧填服务器上 PHP 实际运行的绝对路径（如E:wwwpublic），右侧填你本地项目根目录的绝对路径（如E:/www/public） - 右侧路径务必用正斜杠
/，不要用单反斜杠 - 如果项目在 Docker 或远程服务器，映射关系必须严格一对一，不能只填
/对/
Xdebug 日志里反复出现 “Failed to connect to client”
这不是网络不通，而是 xdebug.client_host 或 xdebug.client_port 和 PhpStorm 监听设置不匹配。Xdebug 3.x 默认用 9003，但 PhpStorm 仍可能沿用旧默认值 9000，或者你在 Docker/WSL 环境下把 client_host 写成了 127.0.0.1，而实际需指向宿主机网关。
注意：Xdebug 3.x 已废弃所有 remote_* 前缀参数，xdebug.remote_host 这类写法不仅无效，还会导致整个 Xdebug 配置块被忽略。
- 确认
php.ini中只有xdebug.client_host和xdebug.client_port（Xdebug 3） - 在 PhpStorm 中：Settings → Languages & Frameworks → PHP → Debug → Xdebug → Debug port，设为和
xdebug.client_port一致（通常9003） - Windows + WSL 场景下，
xdebug.client_host应设为host.docker.internal或宿主机真实 IP，而非127.0.0.1 - 开启 Xdebug 日志：
xdebug.log = "C:/tmp/xdebug.log"，观察连接尝试的目标地址是否和 PhpStorm 监听地址一致
php.ini 没生效），一个错在 IDE 映射层（path mapping 格式不对），两者叠加会让调试看起来“连上了但没反应”，比完全连不上更消耗排查时间。 
