根本原因是PhpStorm GUI启动时不继承shell环境变量，需用which php或where php获取绝对路径后手动配置；CLI与Web使用不同php.ini，Xdebug必须配在CLI版中且端口一致；断点失效多因服务器路径映射未正确设置。
PhpStorm 找不到 php 命令，根本原因不是它坏了
它压根不读你终端里配置好的 PATH——尤其是 macOS 从 Dock 启动、Windows 用快捷方式启动时，GUI 进程根本没加载 shell 的环境变量。所以 which php（macOS/Linux）或 where php（Windows）在终端能跑，PhpStorm 里却报“Command 'php' not found”。
- 必须手动填绝对路径：比如
/usr/local/bin/php或C:\php\php.exe，别信设置页里那个“自动检测”按钮 - 选完后右下角要显示类似
PHP 8.2.12 (cli)，否则就是路径错、权限不足，或缺依赖（如 Windows 缺msvcr120.dll） - 如果用 phpStudy，路径通常是
D:\phpstudy_pro\Extensions\php\php8.2.12\php.exe（版本号随你选的 PHP 变）
CLI 和 Web 用的 php.ini 是两套，改错地方 Xdebug 就不生效
你在 /etc/php/8.2/apache2/php.ini 里加了 Xdebug，对 PhpStorm 完全无效——因为它调用的是 CLI 版本，走的是 /etc/php/8.2/cli/php.ini 或 C:\php\php.ini。
- 在 PhpStorm 内置 Terminal 里运行
php --ini，确认它实际加载的是哪个php.ini - Xdebug 3 配置必须写进这个 CLI 的
php.ini，且端口要和 PhpStorm 一致（默认9003）：
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 确认扩展已加载断点不触发？大概率是服务器路径映射没对上
点了 Start Listening for PHP Debug Connections，断点也打了，但请求一过就没了——Xdebug 发起的调试连接被 PhpStorm 当成未知请求丢弃了，因为 URL 路径和项目物理路径没映射上。
- 进
Settings → PHP → Servers，添加或检查已有服务器 -
Host填localhost，Port填实际 Web 服务端口（如 80 或 8080） - 务必勾选
Use path mappings，把项目根目录（如D:\phpstudy_pro\WWW）映射到/ - 如果项目在 WSL2 里，映射要写成
/mnt/c/path/to/project↔/home/user/project，不能只填一边
WSL2 用户最容易卡在路径和权限上
直接把项目放 /mnt/c/ 下，文件保存失败、Xdebug 断点不命中、Composer 报权限错误——这是 WSL2 文件系统限制导致的，不是 PhpStorm 的锅。
立即学习“PHP免费学习笔记（深入）”；
- 推荐做法：项目放在 WSL2 原生路径下，比如
~/projects/myapp，然后用 PhpStorm 的Open → WSL: Ubuntu方式打开 - 若必须用
/mnt/c，就得手动配 WSL 解释器，并校准双向路径映射，且确保php和composer都走 WSL2 环境 - 别忽略
chmod +x权限问题：WSL2 中.php文件若无执行权限，某些 CLI 工具会静默失败
php --ini、php -m、php -v、映射路径是否真实存在，缺一个，调试就卡住。 
