因为 vs code 在多根工作区下不提供统一 workspacestate，它仅在单根工作区中可用；插件激活时直接读取会返回 undefined，应改用 globalstate 或手动构造键名实现按工作区隔离。
为什么插件激活后 workspaceState 总是 undefined
因为 VS Code 在多根工作区（Multi-root Workspace）下默认不提供统一的 workspaceState，它只在单根工作区中可用。一旦你用 code my-project.code-workspace 启动，extensionContext.workspaceState 就会返回 undefined，而不是空对象或默认值。
实操建议：
- 不要在插件激活时直接读取
workspaceState.get('key')—— 它尚未初始化，且可能永远为undefined - 改用
extensionContext.globalState存储跨工作区通用状态（注意：所有工作区共享同一份数据） - 若需按工作区隔离状态，手动构造键名，例如：
`state_${workspaceFolder.uri.fsPath.replace(/[/\]/g, '_')}_${key}`，再存入globalState - 判断是否处于多根环境：先检查
vscode.workspace.workspaceFolders?.length > 0，再决定走哪条分支
registerCommand 在多工作区里不响应的真正原因
常见现象是插件控制台无报错、命令注册成功，但右键菜单/快捷键完全没反应。本质不是注册失败，而是命令 handler 内部同步访问了未就绪的 vscode.workspace.workspaceFolders 或错误假设了当前编辑器属于第一个文件夹。
实操建议：
- 注册命令时，不要在
activate阶段就依赖vscode.workspace.workspaceFolders[0]或已废弃的vscode.workspace.rootPath - 把路径敏感逻辑移到 command handler 内部，并开头加防御判断：
if (!vscode.workspace.workspaceFolders) return; - 获取当前编辑器所属工作区，优先用
vscode.window.activeTextEditor?.document.uri反推vscode.workspace.getWorkspaceFolder(uri)，而非硬编码索引 - 调试时打开 Output 面板，选你的插件通道，确认 handler 是否被调用；若没进，说明命令根本没绑定到上下文
调试配置 launch.json 在多工作区中失效的典型配置错误
VS Code 的工作区级 launch.json 必须放在 .code-workspace 所在目录下的 .vscode/launch.json 中，且每个 configuration 必须显式指定 "cwd": "${workspaceFolder:xxx}" —— 这里的 xxx 必须和 .code-workspace 文件中对应 folders 条目的 name 字段**完全一致**（大小写敏感），否则变量展开为空字符串，导致调试器找不到 package.json 或 node_modules。
实操建议：
- 不要把
launch.json放在任一子项目根目录下 —— VS Code 不会识别为工作区级配置 - 每个
configuration的type和request要匹配实际运行环境（如"type": "node","request": "launch"），不能共用一个模板 - 用
compound同时启动多个服务时，每个子配置的env（如NODE_ENV）、cwd、preLaunchTask都得单独设，不能继承父级 - 如果
.code-workspace中某个folder没写name，VS Code 会默认取path最后一级目录名（如"path": "./backend"→name是"backend"），但别依赖这个行为，显式写出来更可靠
配置项读取不生效：getConfiguration 缺少作用域参数
插件读取配置时若只写 vscode.workspace.getConfiguration('myext')，默认读的是用户级设置，完全忽略工作区级 .vscode/settings.json 中的覆盖项。这是多工作区下配置“看起来不生效”的最常见原因。
实操建议：
- 读取工作区级配置，必须传第二个参数：指向具体文件夹，例如
vscode.workspace.getConfiguration('myext', workspaceFolder.uri) - 若要兼容单根与多根，先取
vscode.window.activeTextEditor?.document.uri，再用vscode.workspace.getWorkspaceFolder()获取其归属文件夹，最后传入getConfiguration - 避免在插件刚激活时批量读取配置 —— 此时
workspaceFolders可能还未加载完成，应监听vscode.workspace.onDidChangeWorkspaceFolders事件后再读 - 调试时可在命令行执行
code --verbose启动 VS Code，观察输出日志中是否加载了预期的settings.json
workspaceFolder 判断或一个作用域参数，问题就表现为“明明代码写了，就是不运行”。
