根本原因是GUI启动不继承shell环境变量，需用which php或where php获取绝对路径后，在Settings→PHP→Interpreter中手动指定；macOS须用open -a PhpStorm启动，Windows需选php.exe而非php-cgi.exe。

PhpStorm找不到php命令，根本原因不是配置错，而是环境变量没加载

GUI 启动的 PhpStorm（比如双击图标、Dock 启动、开始菜单快捷方式）不会继承 shell 的 PATH，哪怕你在终端里能跑 php -v，IDE 里照样报“Interpreter not found”。

• 先在终端执行 which php（macOS/Linux）或 where php（Windows），拿到绝对路径，例如 /usr/local/bin/php 或 C:\php\php.exe
• 进 Settings → Languages & Frameworks → PHP → Interpreter → Add… → Local，手动浏览并选中这个路径，别点“Auto-detect”
• 选完后右下角必须显示类似 PHP 8.2.12 (cli)，否则说明路径无效——常见原因是权限不足（macOS Gatekeeper 拦截）、依赖 DLL 缺失（Windows）、或该二进制本身无法运行（比如只下载了 NTS 版却配在 Apache SAPI 环境下）

phpinfo() 和 PhpStorm 显示的扩展不一致，是因为 CLI 和 Web SAPI 加载的是两套 php.ini

PhpStorm 调用的是 CLI 模式下的 PHP，而浏览器访问 phpinfo() 看到的是 Apache/Nginx 加载的 Web SAPI 配置。Xdebug、PDO、intl 这些扩展如果只在 /etc/php/8.2/apache2/php.ini 里启用，在 PhpStorm 里就等于没装。

• 在 PhpStorm 内置 Terminal 里运行 php --ini，确认它实际读取的是哪个 php.ini（典型路径：/etc/php/8.2/cli/php.ini 或 C:\php\php.ini）
• 编辑那个 CLI 对应的 php.ini，加入 Xdebug 3 配置（注意版本匹配）：
  zend_extension=xdebug
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=127.0.0.1
xdebug.client_port=9003
• 改完保存，重启 PhpStorm，再在 Terminal 里跑 php -m | grep xdebug 验证是否加载成功

调试断点不触发，90% 是服务器路径映射没对上

点了 “Start Listening for PHP Debug Connections”，打了断点，但请求一发过去就没了反应——这不是 Xdebug 没连上，而是 PhpStorm 根本没把这次 HTTP 请求识别为调试目标，因为 URL 路径和项目本地路径没映射对。

btpanel phpsite 宝塔面板PHP网站

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

• Settings → PHP → Servers，添加一个服务器（比如叫 LocalServer）
• Host 填 localhost，Port 填你 Web 服务实际监听的端口（Apache 默认 80，Nginx 默认 80，内置服务器默认 63342）
• 务必勾选 “Use path mappings”，然后把你的项目根目录（如 D:\phpstudy_pro\WWW）映射到 /；如果项目在子目录（如 http://localhost/myapp/），就映射到 /myapp/
• 映射路径必须严格一致：Windows 下反斜杠不影响，但路径末尾是否带斜杠、大小写、空格都可能让映射失效

用 Docker 做 PHP 解释器时，docker-compose.yml 里的 service 名必须和 PhpStorm 里选的一致

PhpStorm 通过解析 docker-compose.yml 自动挂载代码、拉镜像、启动容器，但它识别服务靠的是 services: 下的键名，不是容器名（container_name），也不是镜像名。

立即学习“PHP免费学习笔记（深入）”；

• 确保 docker-compose.yml 中有明确命名的 PHP 服务，例如：
  services:
  app:
    image: php:8.2-cli
• 在 Interpreter 配置里选择 “Docker Compose”，指定 docker-compose.yml 路径后，下拉菜单里选的必须是 app，而不是 php 或 myapp
• Interpreter path 填 /usr/bin/php 即可，不要写成 /bin/sh -c "php" 或加任何参数，否则 PhpStorm 会校验失败

最常被忽略的其实是 CLI 和 Web SAPI 的分离性——你以为配好了 Apache 的 PHP，就等于配好了 PhpStorm；实际上它们从 ini 文件、扩展、甚至动态库依赖都是两套体系。动手前先搞清当前操作对象是 CLI 还是 Web，能省掉一半排查时间。