PhpStorm 不支持批量重命名文件并自动更新引用，必须分两步：先用 Shift+F6 单文件重构（更新所有引用），再用 Ctrl+Shift+R 全局替换路径；多选文件右键 Rename 仅重命名文件，不更新任何代码引用。
做不到「批量重命名文件并保持引用」——PhpStorm 没有这个功能。你必须拆成两步：单个文件用 Shift+F6 重构改名（自动更新引用），其余文件靠脚本或命令行改名（不碰引用），再用 Ctrl+Shift+R 补路径。
为什么多选文件 + Refactor → Rename 不更新引用
很多人在 Project 视图里 Ctrl+多选一堆 User.php、Post.php，右键选 Refactor → Rename，以为能一键改名+同步所有 require、use、new User()。事实是：
- 该操作只调用系统
rename()，仅修改文件系统名称，完全不扫描代码 - 如果其他文件里写了
require 'User.php';，它不会变成require 'Member.php'; - IDE 甚至不会检查新文件名是否合法（比如含非法字符、与已有文件冲突）
- 唯一安全的引用更新，只发生在单文件
Shift+F6时
正确做法：先单文件重构，再全局补路径
想让 User.php → Member.php 后所有引用都生效，必须按顺序操作：
- 对
User.php单独执行Shift+F6，输入新名Member.php - 勾选
Search in comments and strings（覆盖硬编码路径如require 'User.php'） - 勾选
Search for text occurrences（覆盖注释、JSON、日志等非结构化文本） - 点
Find预览全部变更点，确认无误后点Refactor - 重复以上步骤处理每个要改名的文件——别跳步，这是唯一能保引用的方式
如果你已经用脚本把 50 个文件全改了名，现在满屏 Class not found，那就只剩一条路：Ctrl+Shift+R 全局搜 User.php → 替换成 Member.php，但务必限定 File mask 为 *.php，并勾选 Words only 防止误替 UserRepository.php 里的子串。
立即学习“PHP免费学习笔记（深入）”；
Replace in Path 容易踩的坑
Ctrl+Shift+R 看似简单，实际出错率极高：
- 不填
File mask：默认扫所有文件，.env、package.json、composer.lock全被改，且 IDE 不提示 - 漏勾
Match case：把USER_ID常量错替成MEMBER_ID，运行时报错才暴露 - 没点
Find预览：直接Replace All，结果把 SQL 字符串WHERE user_id = ?改成WHERE member_id = ?，逻辑全崩 - 跨目录路径拼接失效：如
$path = __DIR__ . '/models/' . $class . '.php';这种动态路径，Replace in Path完全无法覆盖，只能人工查逻辑
类移动后引用没更新？不是 Bug，是设计限制
把 app/Models/User.php 移到 app/Domain/User.php 后，发现其他文件里的 use App\Models\User; 没变？这不是 IDE 失效：
- Move 重构只更新当前文件的
namespace，不反向扫描所有use语句 - 如果目标命名空间下已存在同名类（比如
App\Domain\User和App\Models\User同时存在），IDE 会主动跳过use更新，避免歧义 - 第三方库或未加载的 autoload 映射（如
composer.json里漏配 PSR-4）会导致索引缺失，Shift+F6根本找不到引用点 - 改完必须手动运行
composer dump-autoload，否则即使use正确，也会报Class not found
最常被忽略的是：Shift+F6 对类名的重构，不会动配置文件（config/app.php）、路由注解（@Controller("User")）、服务容器绑定（$this->app->bind('user', ...)）——这些全得靠 Ctrl+Shift+F 手动搜原名补全。
