根本原因是GUI启动不继承shell环境变量，需用which php或where php获取绝对路径后，在Settings→PHP→Interpreter中手动指定；macOS须用open -a PhpStorm启动，Windows需选php.exe而非php-cgi.exe。
PhpStorm 找不到 php 命令，根本原因是 GUI 进程没加载 shell 环境变量
你终端里能跑 php -v，但 PhpStorm 里提示 “Invalid interpreter” 或压根不显示版本——这不是 PhpStorm 故障，而是它启动时（macOS 从 Dock、Windows 从快捷方式）不读取你的 ~/.zshrc 或 PATH。它只认绝对路径。
- 先在终端执行
which php（macOS/Linux）或where php（Windows），复制输出结果，例如/opt/homebrew/bin/php或C:\php\php.exe - 打开 Settings → Languages & Frameworks → PHP → Interpreter，点齿轮 → Add Interpreter → Local，**手动浏览并选中这个绝对路径**，别点“Auto-detect”
- 选完后右下角必须显示类似
PHP 8.2.12 (cli)，否则说明路径无效：可能是权限不足（Linux/macOS 没x权限）、依赖缺失（Windows 缺msvcr120.dll）、或路径含中文/空格
CLI 和 Web 的 php.ini 是两套，Xdebug 必须配在 CLI 配置里
你在 Apache 的 php.ini 里加了 Xdebug，但 PhpStorm 调试没反应？因为它调用的是 CLI 版本的 PHP，走的是另一份配置文件。
- 在 PhpStorm 内置 Terminal 里运行
php --ini，确认它实际加载的是哪个php.ini（常见路径：/etc/php/8.2/cli/php.ini或C:\php\php.ini） - 编辑那个 CLI 对应的
php.ini，加入 Xdebug 3 配置（注意不是php_xdebug.dll，而是zend_extension=xdebug）：
zend_extension=xdebug xdebug.mode=debug xdebug.start_with_request=yes xdebug.client_host=127.0.0.1 xdebug.client_port=9003
php -m | grep xdebug，有输出才算真正生效；重启 PhpStorm 不是可选项，是必须项Docker/WSL 远程解释器配错服务名或路径映射，composer install 就会失败
远程解释器能跑 php -v，但 composer install 报 “Cannot find composer.json” 或断点不触发——多半是服务定义或路径没对齐。
- Docker Compose 场景：PhpStorm 只认
docker-compose.yml里services:下的键名（如php），不是容器名或镜像名；Interpreter path 必须填/usr/bin/php，不能写php或/bin/sh -c "php" - WSL 场景：项目千万别放
/mnt/c/xxx，得放原生路径（如~/projects/myapp），然后用 PhpStorm 的 “Open from WSL” 打开；若硬要用/mnt/c/，路径映射必须严格对应：Windows 的C:\dev\myapp→ WSL 的/mnt/c/dev/myapp，少一个/mnt就失效 - 含
fgets(STDIN)的脚本在远程解释器下必然卡住——这不是 bug，是 SSH 默认不分配伪终端；解决办法：Run Configuration 里勾选 “Run with PHP interpreter”，取消 “Use path mappings for script path”，让脚本本地执行、复用远程环境
服务器路径映射不对，Xdebug 断点永远不命中
你点了 “Start Listening for PHP Debug Connections”，断点也打了，浏览器访问也没反应——大概率是服务器映射没配准，Xdebug 发来的调试连接被 PhpStorm 当成非法请求丢弃了。
立即学习“PHP免费学习笔记（深入）”；
- Settings → PHP → Servers，添加新服务器时，“Host” 填
localhost，“Port” 填你 Web 服务的实际端口（如 8080），别默认填 80 后发现 Apache 没跑那儿 - 务必勾选 “Use path mappings”，然后把项目根目录（如
/Users/me/project）映射到 Web 根路径（如/或/var/www/html）；Docker/WSL 环境尤其要注意两边路径是否完全一致 - 验证方式：在浏览器地址栏加
?XDEBUG_SESSION_START=PHPSTORM触发一次请求，看 PhpStorm 右下角状态栏是否弹出 “Debug session started” 提示；没弹就说明映射或 Xdebug 配置链路断了
php.ini 的隐式切换、GUI 进程与 shell 环境变量的割裂、以及 Docker/WSL 路径模型和 PhpStorm 映射逻辑之间的微妙错位——这些地方一错，表面看什么都正常，实际调试和运行全瘫痪。 
