f2跨文档重命名生效的前提是语言服务就绪且符号可识别，否则仅为当前文件文本替换；需满足光标落在符号内、右下角显示正确语言模式、项目根目录存在有效配置文件（如tsconfig.json）并重启服务。
F2 重命名跨文档生效的前提不是快捷键按得对，而是语言服务已就绪、符号可被准确识别——否则它只是当前文件的文本替换，不是真正的跨文档重构。
为什么 F2 只改了当前文件，没动其他引用？
这不是快捷键失效，是语言服务（LSP）没把目标符号识别为“可跨文档追踪的定义”。常见原因包括：
- 右下角语言模式显示
Plain Text或Auto-detect，而非TypeScript/JavaScript/Python - 项目根目录缺失
tsconfig.json（TS）或jsconfig.json（JS），导致引用链无法建立 - 光标停在字符串内（如
"UserManager"）、注释里、点号后（obj.）或括号中，LSP 无法解析出符号上下文 - 按
F12无法跳转到定义——这是最直接的验证方式：跳不到，F2就不会跨文件 - 文件位于
node_modules、dist或未被include规则覆盖的路径下
如何让 F2 真正触发跨文档重命名？
必须满足三个硬性条件，缺一不可：
- 光标**完全落在符号内部**（比如
UserManager的任意一个字母上），不能贴边、不能选中、不能在引号/括号内 - 右下角语言模式明确显示对应语言（如
TypeScript），不是Plain Text；点击可手动切换 - 项目根目录存在有效的配置文件：
tsconfig.json（TS）、jsconfig.json（JS）、pyproject.toml（Python with Pylance）
配置文件至少需包含基础索引规则，例如 JS 项目：
{
"include": ["**/*"],
"exclude": ["node_modules"]
}
改完配置后，执行 Developer: Restart TS Server 或 Developer: Restart Extension Host，等待右下角状态栏出现 TypeScript: Ready 再操作。
重命名后提示 “Some references were not updated” 怎么办？
这不是错误，是语言服务在告诉你：这部分引用超出了静态分析能力范围。典型场景包括：
- 动态属性访问：
obj[variableName]、obj[\"UserManager\"] - 模板字符串拼接：
`new ${className}()` -
eval()或Function构造函数中的符号 - 导入方式模糊：
import * as utils from './utils'，再用utils.UserManager - JSX 属性名、Vue
v-model、JSON key 等非代码区域
此时必须人工核对：
– 先用 Ctrl+Shift+F 搜旧名，确认所有匹配位置
– 对 obj[\"xxx\"] 类写法，开启正则模式搜索 \bobj\["UserManager"\]\b
– 注意大小写和全字匹配（勾选 Match Case 和 Whole Word）
别用 Ctrl+Shift+L 替代 F2 改类名/函数名
Ctrl+Shift+L 是纯文本全选，F2 是语义重构——两者目的不同，混用必然出错：
-
Ctrl+Shift+L会把UserManager改成UserAdmin，同时误伤SuperUserManager和usermanager.js文件名 -
F2只改声明 + 显式引用，自动保留import { UserManager } from './x'中的导出名一致性 - 如果
F2失效，应先修复语言服务，而不是退回到Ctrl+Shift+L—— 后者无法保证类型定义、解构绑定、泛型参数等同步更新
真正需要批量改多个不同符号时（比如 5 个函数名），VSCode 不支持脚本化传参调用 editor.action.rename；只能逐个光标定位 + F2，这是设计限制，不是操作技巧问题。
