多根工作区是跨项目跳转的基础设施，VSCode默认只索引当前文件夹，必须通过“文件>将文件夹添加到工作区”并保存为.code-workspace文件，才能使F12、Shift+F12等功能识别多个项目的符号。
多根工作区是跨项目跳转的基础设施
VSCode 默认只索引当前打开的文件夹，想让 F12、Shift+F12、Ctrl+T 等功能识别多个项目的符号，必须先建立多根工作区（Multi-root Workspace）。这不是可选项，而是前提——没有它，语言服务压根“看不见”其他项目里的代码。
操作很简单：文件 > 将文件夹添加到工作区，重复添加多个项目目录，最后 文件 > 另存为工作区，生成一个 .code-workspace 文件。之后所有导航操作都基于这个工作区上下文生效。
- 添加的每个文件夹必须是独立项目根目录（含
package.json、tsconfig.json或pyproject.toml等标识） - 不能把父目录拖进去再靠排除过滤——VSCode 不会自动识别子项目，必须显式添加
- 保存工作区后，重启 VSCode 才能确保语言服务器完整加载所有路径
TypeScript/JS 项目需显式声明跨项目路径
即使建了多根工作区，F12 跳转仍可能失败，尤其在使用路径别名（如 @utils）或跨项目 import 时。这是因为 TypeScript 语言服务默认只读取单个项目内的 tsconfig.json，不会自动合并多个配置。
解决方法是在主项目（或任意一个项目）的 tsconfig.json 中，用 "include" 显式覆盖其他项目路径：
{
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@shared/*": ["../shared/src/*"],
"@api/*": ["../backend/src/*"]
}
},
"include": [
"**/*.ts",
"../shared/src/**/*",
"../backend/src/**/*"
]
}
-
include是关键：它告诉 TS 服务“这些路径下的文件也要参与类型检查和符号索引” -
paths仅影响模块解析，不扩大索引范围；没include，paths再全也没用 - 路径必须是相对路径，且以
../开头才能跨工作区根目录；写成./shared会被限制在当前项目内
Python 项目依赖 Pylance 的 extraPaths 配置
Python 没有标准的项目配置文件来声明跨目录依赖，F12 和 Shift+F12 能否跳转到其他项目中的模块，完全取决于 Pylance 插件是否知道那些源码在哪。
必须在工作区级 .vscode/settings.json 中配置：
{
"python.analysis.extraPaths": [
"../shared/src",
"../backend/src/lib"
]
}
- 该配置只对当前工作区生效，不能写在用户全局设置里
- 路径是相对于工作区根目录（即
.code-workspace所在位置），不是相对于当前打开的文件夹 - 改完后要手动触发
Python: Restart Language Server，否则新路径不会加载 - 如果目标项目用了
src结构但没设pyproject.toml的[tool.setuptools.py_modules]，Pylance 可能仍无法识别，需补上__init__.py或调整包结构
搜索与跳转失效时优先查语言服务状态
跨项目跳转突然变灰、F12 提示 “No definition found”、Ctrl+T 列不出其他项目的符号——这些问题 90% 不是配置错了，而是语言服务根本没跑起来或没加载完。
验证步骤很直接：
- 看右下角状态栏：是否有
TypeScript Server或Pylance正常运行字样；若显示 “Initializing…” 超过 1 分钟，大概率卡住了 - 按
Ctrl+Shift+P运行Developer: Toggle Developer Tools，切换到 Console，搜language server或failed，常见报错如Cannot find module 'xxx'或ENOENT都指向路径配置问题 - 临时禁用所有非必要插件（尤其是 Vim、GitLens、ESLint 类高频干预编辑器行为的），再重启测试
真正容易被忽略的是：多根工作区 + 跨项目索引 = 更重的语言服务负担。首次加载可能耗时数分钟，期间所有跳转功能都会降级为文本匹配。别急着删配置，先等右下角状态栏从 “Indexing…” 变成绿色图标再说。
