✅ 正确做法是优先用 vscode.window.activeTextEditor?.document.uri 获取 URI，再调用 vscode.workspace.getWorkspaceFolder(uri) 精确匹配所属工作区根目录；若无活动编辑器，则 fallback 到 workspaceFolders[0]，并明确提示用户这是默认取第一个。
如何在插件中准确获取当前活动的工作区根路径
插件运行时，vscode.workspace.workspaceFolders 是唯一可信的多根工作区入口，但它可能为 null（无工作区）或为空数组（仅打开单文件/单文件夹未保存为工作区）。不能依赖 vscode.workspace.rootPath —— 它早已被弃用且在多根场景下始终返回 undefined。
正确做法是先判断是否存在工作区，再根据编辑器焦点决定“当前上下文”：
- 若用户正编辑某个文件，优先用
vscode.window.activeTextEditor?.document.uri获取 URI，再调用vscode.workspace.getWorkspaceFolder(uri)精确匹配所属工作区根目录 - 若无活动编辑器（如只打开了终端或空标签），可 fallback 到
vscode.workspace.workspaceFolders[0]，但需明确告知用户这是默认取第一个，非智能推断 - 避免缓存
workspaceFolders结果 —— 用户可能随时添加/移除文件夹，插件应每次按需调用
为什么 vscode.workspace.getConfiguration() 有时读不到工作区级设置
工作区配置的生效前提是：该配置项**必须显式写入 .code-workspace 文件的 settings 字段中**。插件调用 vscode.workspace.getConfiguration('myExt') 时，VS Code 会按优先级合并用户级、工作区级、文件夹级配置，但只合并它“知道存在”的字段。
常见陷阱：
- 你在
.code-workspace中写了"myExt.enabled": true，但插件代码里读的是config.get('myExt.featureX')—— 后者未声明，返回undefined，不是配置没加载，而是根本没定义 - 某子项目（如
backend/）自己有.vscode/settings.json，其中含"myExt.apiHost"，但该设置属于“文件夹级”，插件调用getConfiguration()时默认作用域是全局，需显式传入 URI：getConfiguration('myExt', uri)才能命中 - 配置值类型不匹配：比如设置里写
"myExt.timeout": "30s"（字符串），但插件代码期望数字，直接parseInt()可能得NaN
多根工作区下，插件如何区分不同项目的语言服务或调试器实例
VS Code 不提供“每个根目录自动隔离插件状态”的机制。插件自身必须维护映射关系：以 workspaceFolder.uri.fsPath 为 key，缓存各项目的独立状态（如连接的调试进程 ID、已加载的语言模型句柄等）。
关键实操点：
- 监听
vscode.workspace.onDidChangeWorkspaceFolders事件，在增删根目录时清理或初始化对应 key 的状态 - 调试场景中，不要假设
vscode.debug.activeDebugSession的workspaceFolder属性一定存在 —— 它只在 launch 配置显式设了"cwd"且匹配某个根目录时才可靠；更稳妥的是从session.configuration中提取cwd字段，再手动匹配workspaceFolders - 语言服务器（LSP）注册时，若支持多根，必须在
createLanguageClient的workspaceFolders参数中传入全部根路径，否则客户端无法向对应服务发送正确的workspace/didChangeWorkspaceFolders通知
插件 UI 元素（状态栏、树视图）如何动态响应工作区切换
状态栏项、树提供者等 UI 组件不会自动感知工作区变化。必须主动监听并刷新 —— 但注意：不是所有变更都需要重绘。
推荐模式：
- 用
vscode.workspace.onDidChangeWorkspaceFolders触发全量刷新（如重建整个树数据） - 用
vscode.window.onDidChangeActiveTextEditor做轻量更新（如状态栏只显示当前编辑文件所在工作区的 Git 分支，无需重建树） - 树视图中每个节点应携带其归属的
workspaceFolderURI，避免点击后因上下文丢失而报错 —— 比如右键菜单命令执行前，先校验node.workspaceFolder是否仍在当前workspaceFolders列表中 - 避免在
resolveTreeItem中同步调用耗时操作（如读取磁盘配置），会导致树展开卡顿；改用getChildren预加载 + 缓存
最易被忽略的一点：插件激活时（activate() 函数），vscode.workspace.workspaceFolders 可能尚未就绪 —— 尤其是 VS Code 启动即打开工作区的场景。必须用 vscode.workspace.onDidOpenWorkspaceFolder 作为兜底监听，而不是只依赖初始值。
