webstorm 重构基于 ast 语义操作，需满足光标位置正确、语言识别为 js/ts、ts 配置生效三条件；shift+f6 重命名、ctrl+alt+m 提取方法等操作均有严格前提，否则退化为文本替换或失败。
WebStorm 的代码重构不是“选中→替换”，而是基于 AST 的语义操作——光标位置、文件语言识别、TS 配置是否生效，三者缺一不可。用错方式会变成文本暴力替换，或直接灰掉不可用。
重命名变量/函数必须用 Shift+F6，且光标不能选中任何字符
你看到的“重命名没反应”“改了字符串里的词”“跨文件不更新”，90% 是因为没走语义路径。Shift+F6（macOS 是 ⇧F6）才是唯一可靠的入口：
- 光标必须停在变量/函数名的任意一个字符上，但**不能选中文字**——选中了就退化为普通查找替换
- 右下角状态栏要显示
JavaScript或TypeScript，不是Plain Text；否则重命名菜单压根不会触发语义分析 - 弹窗里默认不搜注释和字符串，除非你手动勾选
Search in comments and strings；误勾会导致日志里"user ID not found"被改成"customer ID not found" - TypeScript 项目中，接口字段、
declare module里的名字不会被自动同步，得手动改声明文件，或重启 TS Server（Ctrl + Shift + P→Restart TypeScript Server）
Extract Method 报 “Cannot extract fragment”？检查语句块是否闭合
它不接受“差不多能跑”的代码片段，只认语法完整、作用域自洽的语句块。常见卡点：
- 光标要放在待提取代码的**第一行开头**（比如
const result = a + b;行最前面），按Ctrl+Alt+M（macOSCmd+Alt+M） - 不能只选
if分支里的某几行，必须包含整个if (...) { ... }或for (...) { ... }结构 - 避免在模板字符串、对象字面量内部触发；比如
{ name: `${user.name}` }里选中${user.name}就会失败 - 提取后参数顺序按“首次读取变量”排列，不是声明顺序——想调序，先改原代码里变量使用顺序，或提取后立刻用
Change Signature（Ctrl+Shift+P）拖拽调整
移动文件或类后 import 路径没更新？先确认 tsconfig.json 被索引
WebStorm 不是靠猜路径，而是读 tsconfig.json 的 baseUrl 和 paths 配置来重写 import。路径失效基本等于配置没被识别：
- 进
Settings > Languages & Frameworks > TypeScript > Compiler，确保勾选了Use paths mapping from tsconfig.json - 检查
File > Project Structure > Modules，目标目录是否标记为Sources；没标就是普通文件夹，不参与 import 分析 - 刚改过
tsconfig.json？执行File > Invalidate Caches and Restart，否则缓存可能让新配置不生效 - React 函数组件名移动后，
React.memo()包裹名、JSX 标签、自定义 Hook 里的调用点**不会自动更新**，这些得手动处理
Vue 支持 Extract Component，React 必须手动迁移
别指望 WebStorm 给 React 加个快捷键就能抽组件——它只对 Vue SFC（.vue 文件）提供原生支持，且有硬性条件：
- 当前文件必须是
.vue，且右下角显示Vue（不是HTML）；Volar 插件必须启用，Vetur 不行 - 选区必须同时包含完整的
<template></template>和对应的<script setup></script>块，不能只选一半 - React 场景下，可靠做法是：新建
MyButton.tsx→ 粘贴 JSX 和逻辑（删掉return）→ WebStorm 自动提示补import React或defineProps→ 回到原组件删旧代码 → 输入<mybutton>，让它自动补 import</mybutton> - 注意：如果原逻辑用了
useState依赖外部变量，提取后得转成props或用useCallback包一层，否则运行时报ReferenceError
重构真正难的不是操作步骤，而是判断“这段代码到底能不能被安全提取”——WebStorm 不会帮你推理业务逻辑是否可拆，它只校验语法和作用域。每次触发前，先问自己：这段代码有没有隐式依赖？有没有动态 key 或 eval？有没有跨文件的状态耦合？这些地方它一律不分析，全靠人盯。
