.code-workspace 文件是手动创建的 JSON 工作区配置文件，支持多文件夹、专属扩展、跨文件夹任务与调试，其 settings 优先于文件夹级 settings.json 且不干扰其他工作区。
VSCode 的工作区配置不是靠“新建工作区”按钮实现的，而是通过生成和编辑 .code-workspace 文件来完成的——它本质是一个 JSON 配置容器，能覆盖全局/用户级设置，并支持多文件夹、专属扩展启用、任务与调试配置。
什么是 .code-workspace 文件，以及为什么不能只改 settings.json
单个文件夹打开时，VSCode 读取的是该文件夹下的 .vscode/settings.json；但这是“文件夹级”配置，不支持添加多个根目录、无法控制哪些扩展在此工作区启用、也不能定义跨文件夹的 tasks 或 launch。而 .code-workspace 是更高一层的“工作区级”载体：
- 它必须是手动创建的 JSON 文件（如
my-project.code-workspace），不能由 VSCode 自动生成（除非用“另存工作区为…”） - 它可包含多个
"folders"，每个指向不同路径，实现真正多根工作区 - 它的
"settings"会**叠加并优先于**文件夹级settings.json，但不会影响其他工作区 -
"extensions"字段可指定仅在此工作区启用的扩展（需配合"recommendations"和重载）
如何创建并正确配置一个可复用的工作区文件
不要从“文件 → 将文件夹添加到工作区”开始——那只是临时操作。要持久化，必须显式创建 .code-workspace：
- 在系统任意位置新建纯文本文件，命名为类似
backend-workspace.code-workspace - 用 VSCode 打开它（此时是空 JSON），粘贴标准结构：
{
"folders": [
{
"path": "../api"
},
{
"path": "../shared-utils"
}
],
"settings": {
"editor.tabSize": 2,
"files.exclude": { "**/node_modules": true }
},
"extensions": {
"recommendations": ["esbenp.prettier-vscode", "ms-python.python"]
}
}
-
"path"是相对于该.code-workspace文件所在目录的相对路径（也可用绝对路径，但会降低可迁移性） - 保存后，双击该文件即可启动对应工作区；或在 VSCode 中用
File → Open Workspace from File... - 修改后需手动重载窗口（
Cmd/Ctrl+Shift+P→Developer: Reload Window）才能让"extensions"生效
常见错误：配置没生效？可能是这些地方写错了
工作区配置静默失效，通常不是 VSCode bug，而是结构或路径问题：
-
"folders"数组为空或字段名拼错（比如写成"folder"或"Folders"）→ VSCode 会退回到单文件夹模式，且不报错 -
"path"值末尾多了斜杠（如"../api/"）→ 在 Windows 上可能解析失败，建议统一用"../api" - 把工作区文件放在某子文件夹里，但
"path"却写成相对该子文件夹而非工作区文件自身位置 → 路径计算基准永远是.code-workspace文件所在目录 - 在
"settings"里写了只有用户级才支持的项（如"telemetry.enableTelemetry"）→ 这类设置会被忽略，且无提示 - 想禁用某个扩展却在
"extensions"里写"unwanted-ext.disabled": true→ 实际要用"extensions.ignoreRecommendations": ["unwanted-ext"]或直接删掉"recommendations"
工作区配置真正的复杂点不在语法，而在于路径基准的隐式绑定和扩展推荐的异步加载机制——改完 .code-workspace 后不重载窗口，"extensions" 就只是摆设；路径写错一格，整个 "folders" 就被静默跳过。这两处最容易被当成“VSCode 不认配置”。
