新建PHP项目应选空项目而非模板，配置PHP解释器和语言级别，设置内置服务器或Xdebug调试，确保composer.json在根目录并正确映射PSR-4路径。
直接新建空PHP项目，别选“PHP Skeleton”或“Composer Project”开头
PhpStorm 新建项目时，默认弹出的向导里有多个模板选项，PHP Skeleton 和 Composer Project 看起来很“标准”，但实际容易埋坑：前者会强制生成 index.php + vendor 目录结构，后者则自动运行 composer create-project 并联网拉取依赖——如果你只是想写个本地脚本、临时测试或对接已有代码库，这一步纯属多余，还可能因网络/权限/PHP版本不匹配导致创建卡死或目录混乱。
正确做法是：点 “New Project” → 左侧选 “PHP” → 右侧取消勾选 “Create project from template” → 点 “Create”。这样得到的是一个干净的空目录，你后续可以自由放 index.php、config.php 或导入现有文件，IDE 不会擅自干预结构。
项目根目录必须包含 php.ini 或 .phpstorm.meta.php 才能正确识别PHP语言级别
新建完空项目后，PhpStorm 默认不识别 .php 文件为 PHP 类型（右下角状态栏可能显示 “Plain Text”），或者即使识别了，也会报错说 array_key_exists() 未定义、?? 操作符语法错误——本质是项目没绑定 PHP 解释器或语言版本。
解决方法分两步：
立即学习“PHP免费学习笔记（深入）”；
- 打开
File → Settings → Languages & Frameworks → PHP，在Interpreter栏点右侧...，选择你本机已安装的 PHP 可执行路径（如/usr/bin/php或C:\php\php.exe） - 在同一设置页，确认
Language level下拉框选的是你目标版本（如PHP 8.1），不是None或PHP 5.6 - 如果仍不生效，手动在项目根目录下新建一个空文件
.phpstorm.meta.php（注意开头的点），内容可为空，仅用于触发 PhpStorm 的 PHP 上下文识别
Web 服务器配置不等于 PHP 解释器，本地调试需额外配 CLI Server 或 Xdebug
很多人以为设置了 PHP 解释器就能直接右键 index.php → Run 浏览器打开，结果报错 Cannot start server: No web server configured。这是因为 PhpStorm 的 “Run” 功能默认依赖内置 Web 服务器（如 PHP Built-in Server），而它和 CLI 解释器是两套配置。
要让 index.php 可运行并支持断点调试，必须做以下任一操作：
- 启用内置服务器：点击右上角
Add Configuration → + → PHP Built-in Web Server，设置Host为localhost，Port填8000，Document root选项目根目录（含index.php的那一层） - 用 Xdebug 调试：确保 PHP 配置中已启用
xdebug.mode=debug，并在Settings → PHP → Debug中核对端口（默认 9003），然后右键文件选Debug 'index.php' - 若项目依赖 Apache/Nginx，不要指望 PhpStorm 自动代理；需先确保本地服务已启动，再在
Settings → PHP → Servers中添加对应 URL 映射（如http://localhost:8080→ 项目根目录）
Composer.json 放错位置会导致自动加载失效，vendor 目录不被索引
如果你后期手动初始化 Composer（composer init），生成的 composer.json 必须放在项目根目录，且 vendor 目录不能被 PhpStorm 忽略。常见错误是把 composer.json 放进子目录（如 src/composer.json），导致 autoload 规则无法覆盖整个项目，类名跳转失效，use 语句标红。
验证方式：
- 打开
File → Settings → Languages & Frameworks → PHP → Composer，确认Composer executable路径正确，且Configuration file path指向根目录下的composer.json - 执行
composer install后，检查vendor目录是否出现在项目视图中（而非灰色隐藏）；若被忽略，右键该目录 →Mark Directory as → Not Excluded - 在任意 PHP 文件中输入
new GuzzleHttp\Client();，看是否能自动补全并跳转到vendor/guzzlehttp/guzzle/src/Client.php
{
"require": {
"guzzlehttp/guzzle": "^7.8"
},
"autoload": {
"psr-4": {
"App\\": "src/"
}
}
}
这个 composer.json 示例里，"App\\" 映射必须对应真实存在的 src/ 子目录，否则 App\SomeClass 就永远找不到文件——路径错一点，自动加载就全盘失效。
