PhpStorm本身不运行PHP，仅调用本地解释器；必须通过which php或where php获取绝对路径手动配置CLI解释器，并确保对应php.ini启用Xdebug（zend_extension=xdebug、xdebug.mode=debug、xdebug.client_host=127.0.0.1）、端口9003，同时正确设置服务器路径映射与Composer路径。
PhpStorm 本身不运行 PHP，它只调用你本地装好的解释器；所谓“最优设置”，本质是让 IDE 准确识别并稳定复用你已有的 CLI 环境——路径对了，90% 的问题就消失了。
怎么确认 PhpStorm 真的找到了你的 php.exe 或 php
别信 php -v 在终端能跑就万事大吉。GUI 启动的 PhpStorm（比如双击 Dock 图标或开始菜单）通常不加载 shell 配置（~/.zshrc、PATH），所以它根本看不到你配置的 php。
- 在 PhpStorm 内置 Terminal 里执行
which php（macOS/Linux）或where php（Windows），看是否返回有效路径 - 如果返回空或报错，说明 IDE 没继承你的环境 —— macOS 用户改用
open -a PhpStorm启动；Windows 用户确保系统 PATH 已添加 PHP 目录并重启 IDE - 进
Settings → Languages & Frameworks → PHP，点击CLI Interpreter右侧齿轮 →Add → Local，必须用文件选择器指向php.exe（Windows）或具体二进制（如/opt/homebrew/bin/php），不能只填php - 填完后下方应显示 PHP 版本号和 “Xdebug: not installed” 或 “enabled”；若显示为空或报
Cannot run program "php"，就是路径错了或权限不足（Linux/macOS 下补一句chmod +x /path/to/php）
php.ini 配置必须区分 CLI 和 Web 两套环境
你在浏览器里打开 phpinfo() 看到的 Loaded Configuration File，大概率不是 PhpStorm 调试时用的那个。调试走的是 CLI 模式，它读的是 CLI 对应的 php.ini，不是 Apache/Nginx 的那个。
- 在 PhpStorm Terminal 里运行
php --ini，重点看 “Loaded configuration file” 行 —— 这才是你要改的文件 - Xdebug 3 的最小可用配置只有三行，必须加在这份
php.ini末尾：zend_extension=xdebug、xdebug.mode=debug、xdebug.client_host=127.0.0.1（端口默认9003，别写成旧版9000） - 确认扩展文件存在：
extension_dir指向的目录下得有php_xdebug.dll（Windows）或xdebug.so（Linux/macOS） - 别在同一个
php.ini里混用 Xdebug 2 和 3 的指令（比如同时写xdebug.remote_enable和xdebug.mode），会冲突失效
Composer 找不到？不是没装，是 PhpStorm 没看见
PHPStorm 默认不复用 shell 的 $PATH，尤其 GUI 启动时。它不会自动从环境变量里找 composer，所以即使 composer -V 终端能跑，IDE 里仍报 command not found。
立即学习“PHP免费学习笔记（深入）”；
- 进
Settings → Languages & Frameworks → PHP → Composer，勾选Use composer executable - 填入
which composer的结果：macOS/Linux 常见为/opt/homebrew/bin/composer，Windows Scoop 用户是C:\Users\YourName\scoop\shims\composer.bat - 路径里别含空格（如
C:\Program Files\...），PHPStorm 会静默失败 - 如果项目根目录下有
composer.phar，直接指向它也行，但注意每次更新要手动换
路径映射错误导致断点不命中（ThinkPHP/Laravel 等框架高频坑）
断点灰掉、控制台报 Cannot find a local copy of the file on server E:\www\public\index.php，本质是 PhpStorm 收到的调试请求里文件路径（来自 Web Server）和本地项目路径对不上。
- 这不是 Xdebug 没连上，而是路径拼接错位了 —— 常见于 Windows 下 WAMP/XAMPP + 虚拟主机配置
- 进
Settings → Languages & Frameworks → PHP → Servers，添加服务器（如loc.rule.com），关键一步：勾选Use path mappings - 在映射表里，左边填 Web Server 上的绝对路径（如
E:/www/wwwroot/php/thinkphp/shop_order_rule_design/public），右边填你 PhpStorm 里打开的项目根目录（如E:\www\wwwroot\php\thinkphp\shop_order_rule_design） - 注意全部用正斜杠
/，避免反斜杠转义问题；路径结尾不要多加/public或少写一级 - ThinkPHP 8/Laravel 的入口是
public/index.php，但你的项目结构里这文件实际在project-root/public/index.php，映射必须反映这个层级关系
最常被忽略的其实是路径映射的粒度 —— 它不是配一次就一劳永逸，而是每个虚拟主机、每个部署场景都得单独核对。哪怕只是把项目从 E:\www 移到 D:\dev，映射就得重设，否则断点永远灰着。
