${workspaceFolder}不生效的根本原因是未以文件夹方式打开工作区，或launch.json未置于${workspaceFolder}/.vscode/下；多根工作区中命名必须与.code-workspace内path末级完全一致，否则静默失效。
${workspaceFolder} 是工作区变量的核心入口，但直接硬编码路径或混用变量名是多数人踩坑的起点。它不是“万能占位符”，而是一套有明确作用域和匹配规则的上下文引用机制。
为什么 ${workspaceFolder} 有时不生效
这个变量只在「以文件夹方式打开」且该文件夹被识别为工作区根时才解析成功。常见失效场景包括：
- 用
code some-file.py启动 VSCode —— 此时没有工作区上下文，${workspaceFolder}展开为空字符串 - 打开的是单个
.code-workspace文件，但其中folders数组为空或路径字段缺失 - 在
tasks.json或launch.json中用了${workspaceFolder}，但文件没放在工作区根目录下的.vscode/里（必须是工作区根目录，不是任意子目录） - Windows 上写成
"path": "C:\project"—— 反斜杠未转义，JSON 解析失败，变量根本不会被读取
${workspaceFolder:name} 的命名必须与 path 末级完全一致
多根工作区中，VSCode 不允许自定义别名。假设 .code-workspace 内容如下：
{
"folders": [
{ "path": "../frontend" },
{ "path": "../backend/api" }
]
}
那么可用的变量只有：
-
${workspaceFolder:frontend}→ 对应../frontend -
${workspaceFolder:api}→ 对应../backend/api（注意是api，不是backend或api-server）
写成 ${workspaceFolder:backend} 就是无效变量，VSCode 静默忽略，不会报错也不会 fallback。
终端、调试、任务三类环境怎么用变量隔离
同一变量在不同配置位置行为不同，不能复用一套写法：
- 终端环境变量：在
settings.json里用terminal.integrated.env.linux（或对应平台字段），支持${env:PATH}和${workspaceFolder}，但不支持${workspaceFolder:name} - 调试环境变量：在
launch.json的env字段中，可安全使用${workspaceFolder:frontend}，但cwd必须显式设为同值，否则program路径仍会相对工作区根解析 - 任务环境变量：在
tasks.json的options.env中，支持全部变量，但options.cwd同样需手动指定，否则执行路径默认是第一个folders[0]的路径
相对路径 + 变量组合才是跨平台安全写法
不要依赖绝对路径，也不要裸写 ./src。正确姿势是：
- Python 解释器路径：
"python.defaultInterpreterPath": "${workspaceFolder}/venv/bin/python"（Linux/macOS）或"${workspaceFolder}/venv/Scripts/python.exe"（Windows） - 调试入口：
"program": "${workspaceFolder:backend}/dist/server.js"，且配套"cwd": "${workspaceFolder:backend}" - 构建任务输出目录：
"args": ["--outDir", "${workspaceFolder}/dist"]，避免多个项目共用同一dist导致覆盖
所有路径分隔符统一用正斜杠 /，VSCode 内部会自动适配 Windows；变量展开后若含空格，VSCode 会自动加引号，无需手动处理。
.code-workspace 结构松散、folders 路径嵌套或命名不规范，所有基于它的变量引用都会失效——而且往往不报错，只默默走默认逻辑。 
