根本原因是GUI启动不继承shell环境变量，需手动配置PHP绝对路径、CLI版php.ini启用Xdebug（端口9003）、补全PATH环境变量、设置终端常驻及路径映射精确匹配。
直接在 PhpStorm 里跑自定义调试脚本，不是不能用，而是默认配置下大概率失败——根本原因不是脚本写得不对，而是环境、路径、终端生命周期这三关没过。
为什么 php debug.php 在终端能跑，在 PhpStorm 里就报 Command not found
GUI 启动的 PhpStorm（比如 macOS 从 Dock 点开、Windows 双击快捷方式）完全不读你的 ~/.zshrc 或 PATH。它启动时的环境变量是空的，连 php 都找不到。
- 先在终端执行
which php，拿到绝对路径，例如/opt/homebrew/bin/php或C:\php\php.exe - 进 Settings → Languages & Frameworks → PHP → CLI Interpreter → Add → Local，手动指向这个路径，别信“自动检测”
- 确认右下角显示类似
PHP 8.2.12 (cli)，否则就是路径无效或权限问题 - 如果脚本依赖其他命令（如
composer、wp-cli），同样要用which composer拿绝对路径，然后在 Run Configuration 的 Environment variables 里补全：PATH=/opt/homebrew/bin:/usr/local/bin:$PATH
勾选 Execute in the terminal 后窗口秒关，根本看不到报错
这是最常被忽略的细节：勾选后脚本确实在 Terminal 窗口运行，但窗口默认执行完就关闭——你根本来不及看输出或错误。
- 必须去 Settings → Tools → Terminal，勾选
Allow terminal to stay open after command finishes - 同时建议在脚本末尾加一句
read -p "Press any key to continue..."（Linux/macOS）或pause（Windows），确保人工可干预 - 如果脚本本身有交互逻辑（比如
readline()），还要确认 Run Configuration 中勾选了Emulate terminal in output console，否则输入会被吞掉
调试 CLI 脚本时断点不命中，Xdebug 日志显示 Connection refused
CLI 调试失败，90% 是 Xdebug 没配对端口或路径映射，而不是代码问题。
立即学习“PHP免费学习笔记（深入）”；
- 确认你改的是 CLI 的
php.ini，不是 Apache 或 Nginx 的——在 PhpStorm 内置 Terminal 里执行php --ini，盯住Loaded Configuration File那行 - Xdebug 3 最小必要配置只有三行，写进那个 CLI 的
php.ini：zend_extension=xdebug xdebug.mode=debug xdebug.client_host=127.0.0.1
端口默认是9003，别写成旧版9000 - 在 Run Configuration 的
Before launch里加一步：Run External tool→ 执行php -m | grep xdebug，确保扩展已加载 - Server Configuration 的路径映射必须精确匹配：本地项目路径（如
/Users/me/project）要和 Xdebug 发来的fileuri（如file:///Users/me/project/cli.php）完全一致，大小写、斜杠方向都不能错
真正卡住人的地方，往往不是语法或逻辑，而是 PhpStorm 启动时的环境隔离、终端生命周期控制、以及 CLI 和 Web 两套 php.ini 的隐式切换——这些细节不显眼，但缺一不可。
