必须用Shift+F6（Windows/Linux）或⇧F6（macOS），光标精准落在声明名上，且确认范围为“In Project”；Ctrl+R是纯文本替换，会误改字符串、注释、正则及JSON键，F2仅限当前作用域，不跨文件也不更新import引用。
必须用 Shift+F6（Windows/Linux）或 ⇧F6（macOS），光标精准落在声明名上，且确认范围为 “In Project” —— 其他任何方式都容易误改字符串、注释或 JSON 键。
为什么 Ctrl+R 或选中后按 F2 会出错
Ctrl+R 是纯文本替换，user 会变成 customer，但 "user_id" 也跟着变，/user\/\d+/ 正则直接崩；F2 默认只作用于当前作用域（比如单个函数内），不跨文件，也不更新 import 引用。更隐蔽的是：如果光标停在 console.log(user) 的 user 上按 F2，WebStorm 可能只改这一处引用，而非整个变量——它根本没识别到声明源头。
- 快捷键混淆是第一大坑：
Ctrl+R≠Shift+F6，前者是“找-替”，后者才是“语义重构” - 光标位置必须落在声明语句的变量名完整字符范围内，例如
const userName = 'Alice'中的userName，不能在等号前、空格后，也不能选中整个 const 行 - 状态栏右下角语言标识必须是
JavaScript或TypeScript，不是Plain Text，否则 AST 解析直接失效
如何确保跨文件重命名真正生效
WebStorm 默认只在当前文件作用域内重构，除非你手动指定范围。常见失败现象是：改了 export const apiConfig，但其他文件里 import { apiConfig } 没变——这说明对话框左下角显示的是 In File，而不是 In Project。
- 触发
Shift+F6后，务必点开范围下拉框，选In Project；若项目用了tsconfig.json的paths别名，需进Settings > Languages & Frameworks > TypeScript > Compiler，勾选Use paths mapping from tsconfig.json - TypeScript 中重命名导出名（如
export interface User），不会自动更新declare module或types.d.ts里的同名声明，得手动同步 - Vue SFC 的
<script setup></script>中重命名const count = ref(0)，光标必须落在count上，落在ref或括号内会误重构函数本身
哪些情况 WebStorm 根本无法重构
AST 静态分析有天然盲区，这类场景 WebStorm 不会报错，而是静默跳过——你看到“12 处已更新”，其实可能漏了最关键的一处。
-
eval()、new Function()或模板字符串动态拼接的变量名（如${key}Value），重构器完全不可见 - Webpack 别名未被正确索引（
jsconfig.json或tsconfig.json缺少compilerOptions.paths配置） - 变量含 Unicode 或特殊符号（如
user_姓名），WebStorm 默认不视其为合法标识符，Refactor → Rename菜单项直接灰色不可用 - React 组件名重命名后，
JSX标签、React.memo()包裹名、自定义 Hook 内部调用不会自动更新
最易被忽略的点是：即使 WebStorm 显示“全部完成”，也要人工核验三处——console.log 里的字符串是否被误动、JSON.stringify 输出结构是否因键名变更而错位、运行时依赖（如后端 API 字段名）是否与前端变量名强耦合。这些地方不在 AST 覆盖范围内，重构器从不碰它们。
