根本原因是PHPStorm未识别源根或命名空间与目录结构不匹配；需右键标记src/为Sources Root，检查PHP目录设置，并重载composer.json配置。
PHPStorm 自动插入命名空间时为啥不生效
根本原因通常是 PHPStorm 没识别出当前文件属于哪个源根（Source Root），或者目录结构和命名空间约定不匹配。它不会凭空猜——必须明确告诉 IDE：src/ 对应 App/，tests/ 对应 App/Tests/。
- 右键项目根目录 → Mark Directory as → Sources Root（确保
src/或你实际放类的目录被标记） - 检查 File → Settings → Languages & Frameworks → PHP → Directories，确认“Base path”和“Include paths”无误
- 如果用 Composer 自动加载，确保
composer.json中的autoload配置已应用：点击Reload project from composer.json（小刷新图标）
手动补全命名空间时总插错位置或漏写
PHPStorm 默认在文件顶部插入 namespace 声明，但如果你光标不在首行、或已有 后紧跟注释/declare，它可能插到第二行甚至报错“Namespace declaration statement has to be the very first statement”。
- 新建 PHP 文件后，**立刻按
Alt+Insert（Windows/Linux）或Cmd+N（macOS）→ 选PHP Class**，输入类名，IDE 会自动生成带正确命名空间的骨架 - 已有文件需补命名空间？把光标移到
后面、第一行空白处，再按Alt+Enter→Add namespace declaration - 若提示“Cannot add namespace: file already contains one”，检查是否已有
namespace但被注释了（比如// namespace App;），PHPStorm 会把它当真实声明处理
PSR-4 自动映射失效：src/App/Http/Controller/UserController.php 映射不到 App/Http/Controller/UserController
这通常不是 PHPStorm 的锅，而是 PSR-4 配置没对齐。IDE 依赖 composer.json 的 autoload 字段做路径推导，而不是靠文件夹名硬猜。
{
"autoload": {
"psr-4": {
"App//": "src/"
}
}
}
- 确认
src/下的子目录名与命名空间片段严格一致（大小写敏感！Http≠http） - 运行
composer dump-autoload后，在 PHPStorm 中右键项目 →Composer → Reload project - 如果类在
src/Domain/User.php，命名空间必须是App/Domain，不能是App/User—— 否则自动补全类名时找不到对应文件
重命名类时命名空间没联动更新
PHPStorm 支持「安全重构」，但前提是它能准确解析当前类的完整限定名（FQN）。如果命名空间声明缺失、拼写错误，或文件未被识别为 PHP 类文件（比如扩展名是 .inc），重构就会失败或只改类名不改 use 语句。
立即学习“PHP免费学习笔记（深入）”；
- 重构前先确认：编辑器右下角是否显示正确的
Namespace和Class名？没有就说明解析失败 - 右键类名 →
Refactor → Rename（别用普通重命名），勾选Rename usages和Search in comments and strings（按需） - 如果项目混用传统
require和 Composer 加载，PHPStorm 可能无法追踪所有引用，此时需手动检查use语句和字符串中的类名
最常被忽略的一点：PHPStorm 的命名空间感知高度依赖项目索引完整性。一旦发现行为异常，先 File → Invalidate Caches and Restart → Invalidate and Restart，比调半天配置更快。