vscode.workspace.getWorkspaceFolder() 返回 null 说明当前未打开文件夹工作区，仅打开了单个文件或未保存文档；应改用 vscode.window.activeTextEditor?.document.uri 判断 scheme 后提取路径，并对 untitled 类型做降级处理。
vscode.workspace.getWorkspaceFolder() 返回 null 怎么办
调用 vscode.workspace.getWorkspaceFolder() 时返回 null，说明当前编辑器焦点不在任何已打开的工作区（即没通过「Open Folder」打开目录，而是只打开了单个文件）。这个函数只对文件夹级工作区有效，对未保存的 Untitled-1 或孤立文件完全无响应。
- 检查是否已打开文件夹：按
Ctrl+K Ctrl+O（Windows/Linux）或Cmd+K Cmd+O（macOS），看默认路径是不是项目根目录；如果不是，说明当前不属于工作区 - 多根工作区下，该函数只返回当前活动编辑器标签页所属的那个根目录，不会跨根查找
- 若插件需支持单文件场景，必须 fallback 到
vscode.window.activeTextEditor?.document.uri.fsPath提取父目录，并用path.dirname()手动推导
如何安全获取当前文件所在目录（含未保存文件兜底）
依赖 vscode.window.activeTextEditor?.document.uri.fsPath 是最直接方式，但它对未保存文件（untitled: scheme）会返回空字符串或抛错。必须加 scheme 校验和降级逻辑。
- 先判断
vscode.window.activeTextEditor?.document.uri.scheme === 'file'，否则跳过 fsPath 解析 - 对
untitled类型文档，可 fallback 到vscode.workspace.workspaceFolders?.[0]?.uri.fsPath（取第一个工作区根），或提示用户保存后再操作 - 提取目录路径务必用 Node.js 原生
path.dirname(uri.fsPath)，不要用字符串切分 —— Windows 路径含盘符（C:\），正斜杠/反斜杠混用时容易出错
插件里读取用户配置路径时为何 ${workspaceFolder} 不生效
${workspaceFolder} 这类变量只在 tasks.json、launch.json、settings.json 的 JSONC 上下文中被 VSCode 解析，**在插件 TypeScript 代码里直接写字符串是纯字面量，不会自动替换**。这是新手最常踩的坑。
- 想动态拼接路径，得自己解析：比如从
vscode.workspace.getConfiguration().get('myExtension.targetDir')读配置值，再用vscode.workspace.workspaceFolders?.[0]?.uri.fsPath拼接 - 若配置项允许用户填入
${workspaceFolder}/dist，插件需手动做字符串替换：configPath.replace('${workspaceFolder}', workspaceUri.fsPath) - 注意路径拼接必须用
vscode.Uri.joinPath()（VSCode 1.83+ 推荐），而不是path.join()，前者自动处理 URI scheme 和跨平台分隔符
为什么插件打包后 __dirname 指向扩展安装目录而非源码目录
VSCode 插件发布后会被压缩为 .vsix 并解压到 ~/.vscode/extensions/xxx，此时 __dirname 指向的是运行时解压后的物理路径，不是开发时的 src 目录。硬编码相对路径（如 ./templates）会失效。
- 资源文件应统一放在
extensionRoot下（即context.extensionUri），所有路径基于它构建：vscode.Uri.joinPath(context.extensionUri, 'templates', 'config.json') - 不要用
require.resolve()查找模块路径 —— 它在打包后可能找不到，改用vscode.workspace.fs.readFile()+vscode.Uri.joinPath() - 调试阶段可通过
process.env.VSCODE_DEV区分开发/生产环境，开发时用path.join(__dirname, '../src/templates')，发布时走context.extensionUri
path.dirname()，也得先确认 URI scheme、再选对拼接 API、最后验证是否存在 —— 少一步，插件就在某台 Windows 机器上静默失败。 
