不能直接用Ctrl+H全局替换，因它无差别匹配所有字符串，会误改注释、字符串字面量、JSON键名等；安全重命名必须用Shift+F6等基于AST的语义重构方式，确保只更新真实变量引用。
PhpStorm 重命名变量为什么不能直接 Ctrl+H 替换
全局文本替换（Ctrl+H）会无差别匹配所有字符串，改掉注释、字符串字面量、JSON 键名甚至其他同名变量，极易引入 bug。PhpStorm 的「安全重命名」是基于 AST 的语义识别，只作用于当前作用域内真实声明/使用的变量符号。
正确触发重命名的三种方式
必须确保光标落在变量名上（不能在等号后、括号里或引号内），然后：
-
Shift+F6：最常用，弹出重命名对话框，支持预览变更范围 - 右键 → Refactor → Rename
-
Ctrl+T（重构菜单）→ 选Rename
如果快捷键失效，大概率是光标位置不对，或该变量被判定为“不可重构”（比如动态拼接的变量名 ${"user_".$id}）。
批量重命名多个同名变量时的关键控制点
默认情况下，Shift+F6 仅重命名当前作用域（函数/方法内）的变量。要跨作用域批量改，需注意：
立即学习“PHP免费学习笔记（深入）”；
- 勾选对话框中的 Search in comments and strings —— 一般不建议勾，除非你真要改字符串里的内容
- 勾选 Preview usages —— 强烈建议开启，能列出所有将被修改的位置，逐个取消勾选可排除误改项
- 若变量是类成员，会自动区分
$this->name和局部$name；但静态变量self::$cache需手动确认是否包含 - 对
foreach ($items as $item)中的$item重命名，PhpStorm 默认只改本次循环，不会影响其他同名循环变量 —— 这是设计行为，不是 bug
重命名后编译/运行时报错？先查这三处
即使 PhpStorm 显示“0 个问题”，仍可能因以下原因失败：
- 变量名出现在
extract()、compact()或魔术方法（如__get）中 —— 这些属于运行时绑定，IDE 无法静态分析 - PHP 文件被其他语言（如 Twig、Blade）引用，且模板里硬编码了旧变量名
- 使用了 PHP 8.2+ 的只读类属性，但重命名了
public readonly string $id的$id，会导致属性名与构造参数不一致而报错
真正安全的批量重命名，永远依赖预览 + 人工核对，而不是相信“一键完成”。尤其当变量名简短（如 $i, $res）或项目启用了 opcache 时，缓存未清会导致新旧名混用。
