PhpStorm调试失败主因是PHP路径、CLI配置或路径映射错误：需在内置Terminal查which php/where php、php --ini和php -m确认实际PHP及Xdebug；解释器路径须指向php可执行文件而非目录；macOS用open -a启动避免shell环境缺失；Windows避开空格路径；Xdebug 3需zend_extension、xdebug.mode=debug、xdebug.client_host三行且端口匹配；服务器路径映射必须精确对应DocumentRoot。
PhpStorm 本身不运行 PHP，它只调用你本地已安装的 php 可执行文件；配置失败，95% 是路径没对上、CLI 的 php.ini 没改对，或 GUI 启动时压根没加载 shell 环境变量。
怎么确认 PhpStorm 实际用的是哪个 php
别信终端里 php -v 能跑就万事大吉——GUI 启动的 PhpStorm 常常看不到你的 $PATH。必须在 PhpStorm 内置 Terminal 里运行：
-
which php（macOS/Linux）或where php（Windows），拿到绝对路径 -
php --ini，看它实际加载的php.ini路径（比如/opt/homebrew/etc/php/8.2/php.ini） -
php -m | grep xdebug，确认 Xdebug 是否真被 CLI 加载（不是 Apache/Nginx 那个）
如果 php --ini 报错或路径异常，说明 PhpStorm 根本没调到你预期的 PHP，得回头检查解释器路径是否填错、文件有无执行权限（Linux/macOS 下 chmod +x /path/to/php）。
PHP 解释器路径填错的典型表现
Settings → Languages & Frameworks → PHP → Interpreter 页面里，选完路径后右下角不显示 PHP 8.2.12 (cli) 这类字样，就是失败信号。常见原因包括：
立即学习“PHP免费学习笔记（深入）”；
- 点了 “Auto-detect” 或 “Browse”，却选了目录而非
php文件本身（比如选了/usr/local/bin而不是/usr/local/bin/php） - macOS 用 Dock 启动 PhpStorm：它不读
~/.zshrc，which php在终端有效，但在 PhpStorm 里失效；改用终端命令open -a PhpStorm启动 - Windows 上路径含空格（如
C:\Program Files\php\php.exe），PHPStorm 会静默失败；换用短路径（如C:\php\php.exe）或 Scoop 的 shim 路径（如C:\Users\Name\scoop\shims\composer.bat）
Xdebug 不断点？先盯住这三行配置
断点打了、监听开了、浏览器插件也装了，就是不中断——八成是 CLI 的 php.ini 里 Xdebug 配置不全或端口不对。Xdebug 3 最小可用配置只有这三行，缺一不可：
zend_extension=xdebug xdebug.mode=debug xdebug.client_host=127.0.0.1
注意：
-
xdebug.client_port默认是9003，不是旧版的9000；PhpStorm → Settings → PHP → Debug 必须设为同一端口 - 别在 Apache 的
php.ini（如/etc/php/8.2/apache2/php.ini）里配 Xdebug，CLI 和 Web SAPI 加载的是不同 ini 文件 - 扩展文件名要匹配系统：
xdebug.so（Linux/macOS）、php_xdebug.dll（Windows），且extension_dir指向的目录下真有这个文件
服务器路径映射配错，调试连接直接被丢弃
“Start Listening for PHP Debug Connections” 已启用，但请求根本不进断点——根本原因是 Xdebug 发起的调试连接，因路径映射不匹配，被 PhpStorm 当作未知请求丢弃。关键操作：
- Settings → Languages & Frameworks → PHP → Servers，新增一个服务器，Host 填
localhost，Port 填你 Web 服务实际端口（如8080） - 务必勾选
Use path mappings - 左边填项目根目录（如
/Users/name/project），右边填 Web 服务器 DocumentRoot（如/var/www/html或D:\phpstudy_pro\WWW） - 映射必须精确到目录层级，末尾不加斜杠；若项目在子目录（如
http://localhost/myapp/），右边就得填/myapp，不能只填/
路径映射不是可选项，而是调试通道的“门牌号”；填错一个字符，Xdebug 就找不到对应的 PhpStorm 项目上下文，连接直接失败，连日志都不留痕迹。
