workspaceState 在多根工作区中默认为 undefined，因 VS Code 不再提供统一 workspaceState，需改用 globalState 或手动构造键名实现按工作区隔离。
多工作区下 extensionContext.workspaceState 为何总是 undefined
因为 workspaceState 默认只在单根工作区（single-root）中可用；开启多根工作区（Multi-root Workspace）后，VS Code 不再提供统一的 workspaceState，而是要求插件显式绑定到某个工作区文件夹。
实操建议：
- 改用
extensionContext.workspaceState.get(key, defaultValue)前，先检查vscode.workspace.workspaceFolders是否存在且长度 > 0 - 若需跨文件夹持久化状态，改用
extensionContext.globalState（但注意它不区分工作区，所有工作区共享） - 若必须按工作区隔离状态，可手动构造键名，例如
`state_${workspaceFolder.uri.fsPath.replace(/[/\]/g, '_')}_${key}`，再存入globalState - 不要在激活时直接读取
workspaceState的值——它可能尚未初始化，应包裹在vscode.workspace.onDidChangeWorkspaceFolders或命令触发上下文中
registerCommand 在多工作区中注册失败或不响应
常见现象是插件激活了、控制台无报错，但右键菜单/快捷键没反应——本质是命令注册时依赖了未就绪的 vscode.workspace.workspaceFolders，或在非活动工作区上下文中执行了路径敏感逻辑。
实操建议：
- 注册命令时避免同步访问
vscode.workspace.rootPath（已废弃）或vscode.workspace.workspaceFolders[0]；改用命令回调内按需获取 - 若命令需操作当前编辑器所在文件夹，优先用
vscode.window.activeTextEditor?.document.uri反推所属workspaceFolder，而不是假设它属于第一个文件夹 - 对多根场景做防御性判断：在命令 handler 开头加
if (!vscode.workspace.workspaceFolders) return; - 调试时留意输出通道：启用插件的
console.log并观察是否进入 handler，再确认vscode.workspace.workspaceFolders是否为空数组
配置项（package.json contributes.configuration）在多工作区中不生效
VS Code 允许为每个工作区单独设置配置（.vscode/settings.json），但插件若只读取 vscode.workspace.getConfiguration('yourExt') 而不指定作用域，会默认读取用户级配置，忽略工作区级覆盖。
实操建议：
- 读取配置时显式传入作用域：例如
vscode.workspace.getConfiguration('yourExt', vscode.window.activeTextEditor?.document.uri) - 若配置影响全局行为（如日志开关），用
vscode.workspace.getConfiguration('yourExt', null)明确读用户级 - 在
package.json的contributes.configuration.properties中，为每个配置项设置"scope": "resource"（支持工作区/语言级）或"scope": "machine"（仅用户级），避免默认"scope": "window"导致多根下行为不一致 - 测试时务必在多根工作区中打开一个不属于任何文件夹的临时文件（如
Untitled-1），验证配置 fallback 行为是否符合预期
文件监听（FileSystemWatcher）漏触发或监听路径错误
多工作区下，vscode.workspace.createFileSystemWatcher 的 glob 模式若写死相对路径（如 '**/*.json'），会默认相对于第一个工作区文件夹，而非当前编辑文件所在文件夹，导致其他文件夹变更不触发。
实操建议：
- 监听范围应按需创建：对每个
workspaceFolder单独调用createFileSystemWatcher，并使用绝对路径 glob，例如vscode.workspace.createFileSystemWatcher(new vscode.RelativePattern(folder, '**/*.json')) - 避免用字符串拼接路径，始终用
vscode.RelativePattern构造器，它能正确处理多根、符号链接和不同平台路径分隔符 - 监听器应在
onDidChangeWorkspaceFolders回调中动态增删：新增文件夹时添加对应 watcher，移除时 dispose 对应实例 - 注意性能：大量文件夹 + 宽泛 glob（如
**/*）会导致高 CPU，建议限制深度或排除node_modules等目录
多工作区不是“开箱即用”的增强模式，而是把原来隐含的单根假设全部暴露成需要你主动决策的分支点。最容易被忽略的是那些看似无关紧要的“默认值”——比如没传 scope 的配置读取、没检查 workspaceFolders 就直接索引数组、或者以为 workspaceState 还在那儿等着你拿。这些地方不报错，但会让插件在复杂环境里静默失效。
