PHP解释器路径必须手动填写绝对路径，不能依赖自动检测；需先用which php或where php获取真实路径，再在Settings→PHP→Interpreter中添加，并确保CLI版php.ini启用Xdebug且端口为9003。
PHP解释器路径必须手动填绝对路径，不能依赖自动检测
PhpStorm 不会自动从 $PATH 里找 php，尤其 macOS 用 Dock 启动、Windows 用快捷方式启动时，GUI 进程根本没加载 shell 环境变量。终端能跑 php -v ≠ PhpStorm 能用。
- 先在终端执行
which php（macOS/Linux）或where php（Windows），拿到真实路径，例如/opt/homebrew/bin/php或C:\php\php.exe - 打开 Settings → Languages & Frameworks → PHP → Interpreter → 齿轮图标 → Add → Local → 用「…」按钮选中上面那个文件
- 选完后右下角必须显示类似
PHP 8.2.12 (cli)，否则就是路径错、权限不足（Linux/macOS 需chmod +x /path/to/php），或 Windows 缺运行库（如msvcr120.dll）
CLI 的 php.ini 和 Web 的 php.ini 是两套，Xdebug 必须配在 CLI 版本里
你在浏览器访问 phpinfo() 看到的配置，和 PhpStorm 实际调用的 CLI 版本完全无关。Xdebug 断点不触发，90% 是因为改错了 php.ini 文件。
- 在 PhpStorm 内置 Terminal 里运行
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.client_host=127.0.0.1 xdebug.client_port=9003
- 改完重启 PhpStorm，再在 Terminal 里运行
php -m | grep xdebug确认扩展已加载
服务器映射不对，Debug 就永远连不上
点了 Start Listening for PHP Debug Connections，打了断点，但请求一发过去就没了——大概率是路径映射没对上，Xdebug 发来的调试连接被 PhpStorm 当成未知来源直接丢弃。
- 进 Settings → Languages & Frameworks → PHP → Servers → + 添加服务器
- Host 填
localhost，Port 填你实际用的端口（Apache/Nginx 默认 80，内置服务器默认 63342） - 务必勾选
Use path mappings，把本地项目根目录（如D:\phpstudy_pro\WWW\myproject）映射到 Web 路径（如/myproject） - 如果用 phpStudy/XAMPP，Web 路径通常填
/，本地路径指向其www或htdocs子目录
Composer 路径也要手动指定，别信自动发现
PHPStorm 默认不复用你的 shell $PATH，composer 命令找不到是常态，不是插件问题。
立即学习“PHP免费学习笔记（深入）”；
- Settings → Languages & Frameworks → PHP → Composer → 勾选
Use composer executable - 填
which composer的结果，例如/opt/homebrew/bin/composer；Windows 上若用 Scoop，路径可能是C:\Users\YourName\scoop\shims\composer.bat - 避免路径含空格（如
C:\Program Files\...），PHPStorm 会静默失败 - 如果项目里直接用了
composer.phar，就指向那个文件，别绕路
client_port 和 PhpStorm 监听端口必须严格一致，且不能被其他进程占用——这是最容易被跳过、却导致整个调试链路失效的硬性前提。 
