PhpStorm报“Command 'php' not found”是因GUI启动不继承shell环境变量，需用终端执行open -a PhpStorm（macOS）或which/php找到绝对路径后在Settings→PHP→Interpreter中手动指定，并确认Xdebug配置在CLI版php.ini中且服务器路径映射精确匹配。
PhpStorm报“Command 'php' not found”必须手动指定绝对路径
它不读你的PATH环境变量，无论你在~/.zshrc里export得多漂亮，只要从Dock或桌面快捷方式启动，就全白搭。终端里php -v能跑，IDE里照样报错，这是正常现象，不是配置失误。
必须用终端先拿到真实路径：
- macOS/Linux：运行
which php，典型输出如/opt/homebrew/bin/php或/usr/local/bin/php - Windows：运行
where php，常见路径如C:\php\php.exe或C:\phpstudy_pro\Extensions\php\php8.2.12\php.exe
进Settings → Languages & Frameworks → PHP → Interpreter，点齿轮→Add → Local，用文件选择器精准指向上面那个路径。选完右下角必须显示类似PHP 8.2.12 (cli)，否则就是路径错、权限不足（Linux/macOS需chmod +x），或Windows缺msvcr120.dll等运行时依赖。
macOS用户必须用open -a PhpStorm启动才能继承shell环境
从Dock点开的PhpStorm永远拿不到~/.zshrc里的PATH，哪怕你改了系统级launchd.conf也无效。这是macOS GUI进程的限制，不是IDE问题。
立即学习“PHP免费学习笔记（深入）”；
正确做法只有一条：在终端执行
open -a PhpStorm
这样启动的实例才会加载你的shell配置，which php结果才真正可用。如果已经用Dock打开了，关掉重来——别试图在已运行的IDE里“刷新环境变量”，它不支持。
确认Xdebug加载的是CLI版php.ini，不是Apache/Nginx那个
phpinfo()里看到的Loaded Configuration File和PhpStorm调试用的根本不是同一个文件。你在/etc/php/8.2/apache2/php.ini里加了Xdebug，对IDE断点完全没影响。
在PhpStorm内置Terminal里执行php --ini，盯住Loaded Configuration File:那行输出，才是你要编辑的CLI配置文件。常见位置：
- Ubuntu/Debian：
/etc/php/8.2/cli/php.ini - macOS Homebrew：
/opt/homebrew/etc/php/8.2/php.ini - Windows：
C:\php\php.ini（注意不是php.ini-development，得复制重命名启用）
在这个文件末尾追加Xdebug 3最小配置：
zend_extension=xdebug xdebug.mode=debug xdebug.client_host=127.0.0.1 xdebug.client_port=9003
改完重启PhpStorm，再在Terminal里跑php -m | grep xdebug。没输出？检查extension_dir是否指向含xdebug.so（Linux/macOS）或php_xdebug.dll（Windows）的目录。
服务器路径映射不对，断点永远不会触发
点了Start Listening for PHP Debug Connections，断点也打了，但请求一发就过——Xdebug发来的连接被PhpStorm当陌生流量直接丢弃，根本没进调试通道。
进Settings → Languages & Frameworks → PHP → Servers，点+添加：
-
Host填localhost（别填127.0.0.1，某些Xdebug版本解析host敏感） -
Port填你Web服务实际监听端口（Apache默认80，Nginx常用80或8080） - 务必勾选
Use path mappings，把本地项目根目录（如D:\phpstudy_pro\WWW）映射到对应Web路径（如/；若访问URL是http://localhost/myapp/index.php，则映射/myapp）
映射必须精确匹配请求路径，差一个字符，Xdebug回传的文件路径就和PhpStorm本地路径对不上，断点必然失效。改完必须重启PhpStorm，再验证php -m | grep xdebug有输出，才算真正就绪。
