VSCode符号引用功能依赖语言服务正确索引项目结构，缺失tsconfig.json/jsconfig.json、未配置extraPaths、未启用多根工作区或服务未就绪，将导致跨文件跳转、引用查找和F2重命名失效。
VSCode 的符号引用功能（如“转到定义”“查找所有引用”“F2 重命名”）不是开箱即用的魔法，它依赖语言服务能否正确索引整个项目结构。配置不到位，就只能在单文件里跳转，跨文件全失效。
tsconfig.json 或 jsconfig.json 必须存在且 include 覆盖全部源码
TypeScript/JavaScript 项目若缺失配置文件，tsserver 就只把当前打开的文件当独立脚本处理，不会构建项目级 AST。即使你有几十个 src/ 子目录，不显式声明，语言服务也“看不见”。
关键点：
-
include字段必须覆盖所有含符号定义的目录，例如["src/**/*", "shared/**/*"]，不能只写["src/**/*"]却忽略共用模块 -
baseUrl和paths配置别名后，重命名才能穿透@utils/xxx这类导入路径找到真实引用 - 如果项目含多个子包（如 monorepo），每个包都应有自己独立的
tsconfig.json，且根目录建议加一个顶层配置统筹references
Pylance 的 python.analysis.extraPaths 必须手动添加跨项目路径
Python 默认只解析当前工作区根目录下的模块。当你在 A 项目中 import B 项目的某个工具函数时，B 的代码不会被索引——除非你告诉 Pylance：“B 的源码也在我的语义范围内”。
操作方式：
- 在 VSCode 设置中搜索
python.analysis.extraPaths，添加绝对路径或相对于工作区的路径，例如["../common-utils/src"] - 确保 B 项目根目录有
pyproject.toml或至少一个__init__.py，否则 Pylance 不会将其识别为可导入包 - 修改后需重启 Pylance：命令面板输入
Python: Restart Language Server，否则新路径不生效
多根工作区（.code-workspace）是跨项目引用的前提
仅靠打开多个文件夹（File > Open Folder）无法让语言服务统一索引。VSCode 会为每个文件夹启动独立的语言服务器实例，彼此隔离。只有保存为 .code-workspace 文件并显式添加文件夹，才构成真正的“多根工作区”。
必须做的三件事：
- 通过
File > Add Folder to Workspace...把所有相关项目加入同一窗口，再File > Save Workspace As...生成.code-workspace - 确认状态栏右下角语言标识显示正常（如 “Python” 不是灰色或 “Plain Text”）
- 打开输出面板（
Ctrl+Shift+U），切换到Pylance或TypeScript Server日志，查看是否出现类似Found 1234 files in workspace的索引完成提示
重命名失败时优先查 textDocument/rename 报错日志
F2 按下没反应、或只改了当前文件，大概率是语言服务返回了空响应或明确拒绝请求。这不是 UI 问题，而是后端协议层面失败。
快速定位方法：
- 打开开发者工具（
Ctrl+Shift+P→Developer: Toggle Developer Tools） - 切换到 Console 标签页，过滤关键词
rename或textDocument/rename - 常见错误：
No definition found（符号未被索引）、Request textDocument/rename failed（服务器崩溃）、Not supported（当前文件类型不支持，如 .vue 中未启用 Volar）
最易被忽略的一点：语言服务索引是异步的，刚打开大型工作区时，“查找引用”可能为空——不是配置错了，是还没索引完。等右下角状态栏不再显示“Indexing…”或“Analyzing…”，再试。
