PHP解释器必须指向可执行文件（如C:\php\php.exe或/opt/homebrew/bin/php），而非安装目录；路径错误将导致代码提示、调试、运行全部失效，且IDE Encoding与Project Encoding须同时设为UTF-8，否则引发中文乱码等静默错误。
PHP 解释器没配对，后续所有功能（代码提示、调试、运行）都会失效，不是“能跑就行”的问题，而是根本不可用。
PHP 解释器路径必须指向可执行文件，不能只选目录
很多人在 Settings → Languages & Frameworks → PHP 里点“Add Interpreter”后，误选了 PHP 安装目录（如 C:\php），结果 PhpStorm 报错“Cannot detect PHP version”。它要的是具体可执行文件：php.exe（Windows）、php（macOS/Linux）。路径错误会导致 CLI Interpreter 显示为“Unknown”，php -v 在终端能运行 ≠ PhpStorm 能识别。
- Windows 常见正确路径：
C:\php\php.exe或C:\xampp\php\php.exe - macOS Homebrew 用户：
/opt/homebrew/bin/php（Apple Silicon）或/usr/local/bin/php（Intel） - 确认方式：在 PhpStorm 的 Interpreter 配置窗口右侧，会实时显示读取到的
PHP_VERSION和已启用扩展列表，空或报错即失败
编码必须统一设为 UTF-8，否则中文注释/输出乱码无法根治
IDE Encoding 和 Project Encoding 分离设置是 PhpStorm 的经典陷阱。只改其中一个，比如仅设 Project Encoding 为 UTF-8，但 IDE Encoding 仍是 GBK，新建文件仍会默认用 GBK 编码保存，导致 file_get_contents() 读中文路径失败、json_encode() 返回 null 等静默错误。
- 操作路径：
File → Settings → Editor → File Encodings - 必须同时修改三项：
IDE Encoding、Project Encoding、Default encoding for properties files，全部设为UTF-8 - 已有乱码文件：右下角状态栏点击当前编码（如 GBK），选择
Reload as UTF-8（非 Convert），再手动修正字符
内置 Web 服务器端口冲突时，不报错但页面白屏
PhpStorm 内置服务器默认监听 63342 端口（旧版）或动态端口（新版），但若该端口被 Docker、另一实例或杀毒软件占用，它不会弹窗警告，而是静默降级为“无法提供服务”——浏览器打开 http://localhost:63342 时直接返回空白页或连接被拒，日志里也无明显错误。
立即学习“PHP免费学习笔记（深入）”；
- 验证方式：打开
Help → Diagnostic Tools → Debug Log Settings，添加 loggercom.jetbrains.php.webserver，重启后看日志是否有Failed to start built-in web server - 解决方法：
Settings → Build, Execution, Deployment → Debugger → Built-in server configuration，手动指定一个未被占用的端口（如8081） - 注意：
Document root必须设为项目根目录（不是public/子目录），否则路由解析失败
零配置调试依赖浏览器插件和 php.ini 严格匹配
勾选了 Start Listening for PHP Debug Connections，断点也打了，但浏览器刷新后毫无反应——大概率是 Xdebug 版本与 php.ini 配置、浏览器插件三者不兼容。Xdebug 2 和 Xdebug 3 的配置项完全不同，混用必失败。
- Xdebug 3 正确最小配置（写入
php.ini）：zend_extension=xdebugxdebug.mode=debugxdebug.client_host=127.0.0.1xdebug.client_port=9003 - 必须禁用 Xdebug 2 风格的旧参数（如
xdebug.remote_enable），否则 Xdebug 3 直接拒绝启动 - 浏览器必须安装对应插件（Chrome 推荐
Xdebug Helper），且插件开关需手动启用（图标变绿色），不能只靠 GET 参数?XDEBUG_SESSION_START=PHPSTORM
最容易被忽略的是路径映射（Path Mapping）：当用内置服务器调试时，PhpStorm 默认认为请求 URL 中的文件路径与本地项目路径完全一致；一旦项目结构含符号链接、Docker 挂载或使用 Vagrant，就必须在 Settings → PHP → Servers 中手动配置远程路径到本地路径的映射，否则断点永远不命中。
