直接替换会出错而重构不会，因全局文本替换会误改字符串、注释、正则、json键等，而重构基于ast语义分析，仅修改目标变量的作用域内引用。
为什么直接替换会出错，而重构不会
直接用 Ctrl+R（Windows/Linux）或 Cmd+R（macOS）全局文本替换变量名，很可能把字符串、注释、其他同名变量甚至 JSON 键名也一并改掉。比如把 user 改成 customer，结果 "user_id" 变成 "customer_id"，或正则里写的 /user\/\d+/ 被误改，代码直接报错。重构是语义级的重命名，WebStorm 会解析 AST，只改当前作用域内真正声明/引用该变量的位置，跳过字符串、注释、其他作用域的同名变量。
正确触发变量重命名的快捷方式和前提
光标必须精准停在要重命名的变量名上（不能在空格或符号上），且该变量已被 IDE 正确识别为可重构目标（比如已声明、有明确类型推导或有 JSDoc 注解）。否则右键菜单里 Refactor → Rename 是灰色的。
-
F2是最稳的快捷键：聚焦变量名后按一次，输入新名，回车确认 - 右键菜单选
Refactor → Rename效果相同，适合不确定快捷键时 - 如果变量是
const/let声明的顶层变量，或函数参数、for循环中的let变量，重构默认作用域是“当前文件”；若它是export的，会自动弹出“是否更新所有导入处”的提示 - 对 TypeScript 接口字段、类属性重命名，同样适用
F2，但需确保 tsconfig.json 中allowSyntheticDefaultImports和esModuleInterop配置合理，否则跨文件重构可能漏掉某些 import 别名引用
常见失败场景和应对办法
重构失败往往不是功能问题，而是上下文没被识别清楚。典型现象包括：按 F2 没反应、弹窗里预览修改位置为空、改完后某处调用仍报 undefined。
- 变量由
eval()、new Function()或模板字符串动态生成（如`${key}Name`）——这类无法静态分析，重构器必然跳过，得手动检查 - 使用了 Webpack 别名（如
@/utils）但jsconfig.json或tsconfig.json未配置compilerOptions.paths，导致跨文件引用识别失败 - 变量名含 Unicode 或特殊符号（如
user_姓名），WebStorm 默认不将其视为合法标识符，此时重构菜单不可用；建议改用 ASCII 命名规范 - 在 Vue SFC 的
<script setup></script>中重命名响应式变量（如const count = ref(0)），要确保光标落在count上而非ref或括号内，否则会误重构ref函数本身
重构后必须人工核验的三个地方
即使 WebStorm 显示“12 处已更新”，也不能完全信任。尤其当项目用了 Babel 插件、自定义 ESLint 规则或运行时依赖反射（如 Object.keys(obj) 动态访问），这些都逃不出静态重构的覆盖范围。
- 检查所有
console.log()和调试语句里是否还残留旧变量名（IDE 默认不重构日志里的字符串） - 搜索项目中
JSON.stringify(后面是否硬编码了旧字段名，比如JSON.stringify({ user: x }) - 打开终端执行
git grep -n "oldVariableName"（把oldVariableName换成实际旧名），确认没有漏网之鱼——特别是 Markdown 文档、测试用例断言、Mock 数据文件
grep 快速扫一遍，比事后 debug 半小时强得多。
