PhpStorm不读取系统PATH，必须手动配置PHP解释器绝对路径；需在终端执行which php或where php获取路径，于Settings→PHP→Interpreter中手动添加，并确认CLI php.ini启用Xdebug且端口为9003，同时严格匹配Servers路径映射。
PhpStorm不读取系统PATH，必须手动填绝对路径
你终端里能跑 php -v，不代表PhpStorm知道php在哪——GUI启动的PhpStorm进程压根不加载shell的PATH环境变量，尤其macOS从Dock点开、Windows用快捷方式启动时最典型。
解决办法只有一条：在终端里先运行 which php（macOS/Linux）或 where php（Windows），拿到真实路径，比如 /opt/homebrew/bin/php 或 C:phpphp.exe，然后在 Settings → PHP → Interpreter 页面，点击齿轮 → Add Interpreter → Local，**手动浏览选中这个文件**，不能靠“自动检测”。
- 选完后右下角必须显示类似
PHP 8.2.12 (cli)，否则就是路径错、权限不足，或该二进制缺依赖（如Windows缺msvcr120.dll） - 别把Apache/Nginx用的php.ini和CLI用的搞混——PhpStorm调用的是CLI版本，
php --ini在PhpStorm内置Terminal里执行，才能确认它实际加载的是哪个php.ini
CLI php.ini 和 Web SAPI 的配置完全隔离
你在 /etc/php/8.2/apache2/php.ini 里开了Xdebug，对PhpStorm毫无作用；反过来，在CLI的php.ini（通常是 /etc/php/8.2/cli/php.ini 或 C:phpphp.ini）里配了Xdebug，浏览器访问却没反应——这是常态，不是bug。
Xdebug 3 必须按CLI上下文配，且端口要和PhpStorm Debug设置一致：
立即学习“PHP免费学习笔记（深入）”；
-
zend_extension=xdebug（Linux/macOS是.so，Windows是.dll，但Xdebug 3起可省略后缀） xdebug.mode=debug-
xdebug.start_with_request=yes（或设为trigger配合浏览器插件） -
xdebug.client_host=127.0.0.1（别写localhost，某些系统解析慢或失败） -
xdebug.client_port=9003（PhpStorm默认监听此端口，别改除非同步改IDE设置）
改完重启PhpStorm，再在Terminal里跑 php -m | grep xdebug 确认扩展已载入。
Servers路径映射错一个字符，断点就永远不触发
点了 Start Listening for PHP Debug Connections，断点也打了，浏览器装了Xdebug Helper，但就是不停——90%是Servers里的路径映射没对上。
映射不是“看着像就行”，而是要求：**浏览器请求的URL路径 → PhpStorm项目内文件的绝对路径**，必须逐字匹配。
- 比如项目根目录是
/Users/me/project，Web服务器DocumentRoot是/var/www/html，那就要在 Settings → PHP → Servers 里新建条目，Host填localhost，Port填80，勾选Use path mappings，然后把/var/www/html映射到/Users/me/project - 如果用PhpStorm内置服务器（
http://localhost:63342），映射目标必须是项目根目录，且URL路径前缀要和实际访问路径一致（如访问http://localhost:63342/index.php，映射起点就得是/） - Windows路径注意反斜杠转义问题，建议全用正斜杠或双反斜杠：
C:/project或C:\project
调试连接失败时，先查Xdebug日志而不是重配
比反复改配置更高效的做法，是让Xdebug自己说话。在CLI的php.ini里加一行：
log_level=10 xdebug.log=/tmp/xdebug.log
然后触发一次调试请求（比如刷新页面），立刻去看日志文件。里面会明确告诉你：
- 连不上
127.0.0.1:9003（防火墙/端口被占/PhpStorm没监听） - 收到连接但拒绝（路径映射不匹配）
- 根本没发请求（
xdebug.start_with_request没生效，或浏览器插件没启用）
日志路径要确保PHP进程有写权限，/tmp在macOS/Linux下安全，Windows建议用C:/temp/xdebug.log并提前建好目录。
真正卡住的地方，往往不是“怎么配”，而是“哪一层没对齐”——CLI解释器、CLI配置、IDE监听端口、服务器路径映射、Xdebug日志输出，五层环环相扣，漏掉任意一环，调试就静默失效。
