根本原因是光标没在文件首行首列，php要求namespace声明必须位于文件最开头，任何空白字符或bom都会导致该错误。
新建PHP类时namespace插到第二行或报“Namespace declaration has to be the very first statement”
根本原因是光标没在<?php 后紧邻的空白行——PHPStorm只认“文件开头第一行可写位置”。它不会跳过declare(strict_types=1);、BOM、空行或注释去硬塞。
- 新建文件后，**立刻按
Alt+Insert（Windows/Linux）或Cmd+N（macOS）→选PHP Class**，输入类名，IDE会自动生成带正确命名空间的骨架（<?php后直接跟namespace） - 已有文件要补命名空间？把光标移到
<?php后面、**第一行空白处**（不能有空格、不能有换行、不能有注释），再按Alt+Enter→Add namespace declaration - 若提示
Cannot add namespace: file already contains one，检查是否已有// namespace App;这类被注释掉的声明——PHPStorm会把它当真实声明处理
移动PHP文件后命名空间没更新，不是功能失效而是条件不满足
PHPStorm的Refactor → Move（F6）只在严格符合PSR-4结构时才改namespace和use语句。它不靠文件夹名猜，而靠composer.json里的映射关系推导。
- 右键项目中实际放类的目录（如
src），选Mark Directory as → Sources Root - 确认
composer.json含合法PSR-4配置，例如：{"autoload": {"psr-4": {"App\": "src/"}}}，然后点右上角Composer图标→Reload project from composer.json - 移动前，原文件顶部
namespace必须完整、无注释、且是<?php后的第一个语句（declare后必须换行） - 目标路径必须能被推导出新命名空间：比如从
src/Http/Controller移到src/Domain/User，才会尝试改成AppDomainUser
修改目录默认命名空间前缀，本质是改PSR-4映射而非IDE设置
PHPStorm没有“为某个目录设置默认namespace”的独立开关。所谓“修改前缀”，实际是调整composer.json中该目录对应的PSR-4根命名空间，并让IDE重新加载。
- 编辑
composer.json的autoload.psr-4字段，把旧映射如"App\": "src/"改成新前缀如"MyApp\": "src/" - 保存后，点击右上角Composer图标→
Reload project from composer.json（不是Reload project from disk） - 之后新建类或移动文件时，IDE才会基于
MyApp推导命名空间；已有文件的命名空间不会自动批量替换，需手动或用Refactor → Rename逐个修正 - 如果改完仍不生效，检查
src/是否仍被标记为Sources Root——重载后有时会丢失标记
$this->无补全、new后类名不弹出，根源常在命名空间与PSR-4错位
补全失效表面是提示问题，深层往往是类型信息断链：IDE找不到类定义位置，自然无法推断$this类型或new可选类。
- 运行
composer dump-autoload -o确保自动加载映射最新，否则vendor/autoload.php里没注册新类 - 检查
src/App/Http/Controller/UserController.php是否真对应AppHttpControllerUserController——路径层级、命名空间、类名三者必须完全一致 - 若用Laravel，
App前缀被改过（如MyApp），但config/app.php里的namespace没同步，会导致门面和辅助函数补全失败 - 补全慢或卡顿？关掉
Settings → Editor → General → Code Completion → Include non-project items，避免扫描整个vendor目录
composer.json没重载，或src/没重标Sources Root——这两步漏掉任何一环，IDE就当没这回事。命名空间不是IDE“记下来”的配置，而是每次操作时实时查composer.json推导的结果。php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
