能跑起来不等于配置到位——关键在于解释器路径、Web服务器配置、Xdebug端口及CLI/Web一致性四层必须对齐：解释器须指向php.exe或php可执行文件，Web服务器需按实际环境（Apache/Docker/内置）配置Host与路径映射，Xdebug 3必须设xdebug.mode=debug且client_port与PhpStorm Debug端口一致（默认9003），CLI与Web解释器应为同一PHP实例。
能跑起来不等于配置到位——很多 PHP 开发者在 PhpStorm 里写代码、php -v 能执行、甚至 phpinfo() 也能显示，但调试断点不触发、路径映射错乱、Xdebug 连不上、CLI 命令行为和 Web 不一致，问题全出在「解释器」和「服务器」两层配置没对齐。
PHP 解释器路径必须指向 php.exe（Windows）或 php（macOS/Linux）
很多人误把整个 PHP 安装目录或 php.ini 路径当解释器填进去，结果 PhpStorm 报错：Cannot resolve PHP executable 或直接跳过版本检测。
- Windows 下必须选到具体可执行文件，例如：
C:\php\php.exe，不是C:\php\ - macOS/Linux 下常见路径是：
/usr/bin/php（系统自带）、/opt/homebrew/bin/php（Homebrew）、或/usr/local/bin/php（手动编译） - 如果用了 phpStudy、XAMPP、MAMP 等集成环境，路径通常是：
D:\phpstudy_pro\Extensions\php\php_8.2.12\php.exe（注意版本子目录） - 填完后 PhpStorm 会自动读取
PHP_VERSION、已启用扩展（如mbstring、curl），若列表为空，说明路径错误或该 PHP 实例无法正常启动
Web 服务器配置必须匹配实际运行方式
PhpStorm 自带的「PHP Built-in Web Server」和你用 Apache/Nginx 启动的项目，底层执行环境完全不同——前者走 CLI 模式，后者走 SAPI（如 apache2handler）。混用会导致 $_SERVER 变量缺失、重写规则失效、session 机制异常。
- 如果你用 phpStudy / XAMPP / 自建 Apache：必须在
Settings → PHP → Servers中添加真实服务器，Host 填localhost，Port 填对应端口（如 80 或 8080），并勾选Use path mappings - 路径映射必须严格一对一：本地项目根目录（如
D:\phpstudy_pro\WWW\myapp）→ Web 根路径（如/myapp/），不能只映射到/除非你真把项目放进了 WWW 根下 - 如果只用 PhpStorm 内置服务器（右键 →
Run 'index.php'），它默认监听http://localhost:63342，且不支持.htaccess和 URL 重写，适合纯 API 或简单脚本，不适合 Laravel、ThinkPHP 等框架
Xdebug 3 配置必须与 PhpStorm 监听端口一致
最常踩的坑是 PhpStorm 在监听 9003，而 php.ini 里写的是 9000 或漏配 xdebug.mode=debug，导致断点灰色不可用。
立即学习“PHP免费学习笔记（深入）”；
-
php.ini中至少要包含这 4 行（Xdebug 3+）：zend_extension=xdebugxdebug.mode=debugxdebug.client_host=127.0.0.1xdebug.client_port=9003 - 确认
xdebug扩展已加载：php -m | grep xdebug（Linux/macOS）或php -m搜索xdebug（Windows） - PhpStorm 必须开启监听：
Run → Start Listening for PHP Debug Connections（快捷键Ctrl+Alt+Shift+F9） - 浏览器需配合 Xdebug Helper 插件，并点击「Debug」按钮触发请求；单纯刷新页面不会连接调试器
CLI 解释器和 Web 解释器最好保持同一份
很多人为图省事，Web 用 phpStudy 的 PHP，CLI 却用系统 PATH 里的另一个版本，结果 composer install 装的扩展在 Web 环境里找不到，或 phpunit 提示 Class not found。
- 在
Settings → PHP → CLI Interpreters里，确保 CLI 解释器路径和上面配置的 Web 解释器完全一致 - 验证方式：在 PhpStorm 终端里执行
which php（macOS/Linux）或where php（Windows），输出应和解释器路径一致 - 若使用 Docker 或远程解释器，CLI 和 Web 必须指向同一容器内 PHP 实例，否则 autoload、扩展加载、时区设置都会错位
真正卡住人的从来不是「怎么配」，而是「哪一层配错了」——解释器路径、服务器映射、Xdebug 端口、CLI 与 Web 的一致性，四者中任意一个偏差，都会让调试变成猜谜。动手前先明确你用什么方式跑 PHP（内置 server？Apache？Docker？），再逐层对齐，比反复重启 PhpStorm 有效得多。
