必须先配置PHP解释器，否则Ctrl+Shift+F10会报错“No executable file found”；PhpStorm不读系统PATH，需在Settings→Languages & Frameworks→PHP→CLI Interpreter中手动指定php.exe或/usr/bin/php路径。
PhpStorm 报 PHP executable not found 或调试时提示 “No PHP interpreter configured”，本质是它压根没找到你本地装的 PHP 可执行文件路径——不是插件问题，也不是 Xdebug 配置错，而是最底层的 php.exe（Windows）或 php（macOS/Linux）根本没被识别。
检查 PHP 解释器是否真的被 PhpStorm 识别
很多人点开 Settings → PHP 后看到“未配置”，就直接去改 php.ini，其实第一步该确认的是：PhpStorm 知不知道你的 PHP 在哪。
- 打开
Settings → PHP（Windows/Linux 快捷键Ctrl+Alt+S，macOS 是Cmd+,） - 看右侧 “CLI Interpreter” 区域：如果显示
Not configured或路径是灰色/空的，说明没连上 - 点击右上角
+→Add...→Local - 在弹出窗口中，**不要手动输路径**，先点
...按钮，用文件选择器定位到你实际安装的php.exe（Windows）或php（macOS/Linux） - 选中后，PhpStorm 会自动读取版本号、
php.ini路径、已启用的扩展（包括 Xdebug 是否加载）
如果点 ... 后找不到可执行文件，说明你根本没装 PHP，或者只装了 phpstudy/xampp 但没把 bin 目录加进系统 PATH —— 此时别硬配，先在终端运行 which php（macOS/Linux）或 where php（Windows）确认是否存在。
常见路径陷阱：phpstudy、XAMPP、Homebrew 用户必看
不同安装方式下，PHP 可执行文件位置差异极大，且 PhpStorm 不会自动猜：
立即学习“PHP免费学习笔记（深入）”；
-
phpstudy_pro：默认路径是
C:\phpstudy_pro\Extensions\php\php_x.x.x\php.exe（x.x.x 是版本号），注意不是phpstudy_pro\php\下那个空文件夹 -
XAMPP：通常是
C:\xampp\php\php.exe（Windows）或/Applications/XAMPP/xamppfiles/bin/php（macOS） -
Homebrew（macOS）：路径类似
/opt/homebrew/bin/php或/usr/local/bin/php，但需确认brew services list | grep php是否正在运行 -
Linux 手动编译：大概率在
/usr/local/bin/php，但更稳妥的是运行find /usr -name "php" -type f -executable 2>/dev/null
如果你改过系统 PATH，PhpStorm **不会自动继承更新后的 PATH**，必须重新手动指定解释器路径，否则即使终端能跑 php -v，IDE 里照样报错。
为什么选对解释器后，Xdebug 还不工作？
选中正确的 php.exe 只是第一步。Xdebug 调试失败，90% 是因为当前解释器加载的 php.ini 里没启用 Xdebug，或版本不匹配。
- 在
Settings → PHP → CLI Interpreter页面，点右侧的...（“Show details”），再点Open in Editor，它会直接打开该解释器正在用的php.ini - 搜索
xdebug，确认有且仅有一组有效配置（Xdebug 3 和 2 的写法完全不同） - Xdebug 3 正确写法示例（路径按你本地实际调整）：
zend_extension = "C:/phpstudy_pro/Extensions/php/php_x.x.x/ext/php_xdebug.dll" xdebug.mode = debug xdebug.client_host = 127.0.0.1 xdebug.client_port = 9003
- 保存
php.ini后，**必须重启 PhpStorm**（不是重载项目），否则新配置不生效
特别注意：如果你用的是 phpstudy_pro，它的控制面板里“PHP 设置”页面改的 php.ini 往往不是 PhpStorm 实际读的那个 —— 它可能指向另一个独立的配置副本。
调试启动时卡在 “Waiting for connection…” 怎么办
这表示 PhpStorm 已监听端口，但 Xdebug 没连上来，和“找不到 PHP”是两个阶段的问题，但常被混为一谈。
- 先确认 PhpStorm 的 Debug 监听已开启：顶部菜单
Run → Start Listening for PHP Debug Connections（按钮图标是 ?） - 检查 Xdebug 日志是否生成：在
php.ini中加xdebug.log = "C:/tmp/xdebug.log"，然后运行脚本，看日志里有没有Connecting to configured address/port或Failed to connect - Windows 上杀毒软件（尤其是 360、腾讯电脑管家）会拦截
php.exe建立网络连接，临时禁用试试 - macOS/Linux 用户注意：如果用了 Docker 或 WSL，
xdebug.client_host不能写localhost，得写宿主机真实 IP（如10.0.2.2）
最易忽略的一点：PhpStorm 的 Debug 配置里，“Filter debug connection by IDE key” 如果勾选了，而你的脚本没传 XDEBUG_SESSION_START=xxx 或没在浏览器装 Xdebug helper 插件，连接就会静默失败——这个选项默认不勾选，但有人手动开过就忘了关。
