VSCode Settings Combiner

在团队协作中安全拆分 VSCode 工作区配置：团队公共配置进 git，个人配置各自维护，插件自动合并成 VSCode 实际读取的 .vscode/settings.json 与 .vscode/tasks.json。

功能

打开工作区时（以及配置文件变化时）自动合并生成：

• .vscode/settings.json ← team.settings.json + team.settings.<platform>.json + user.settings.json + 现有 settings.json

• .vscode/tasks.json ← team.tasks.json + team.tasks.<platform>.json + user.tasks.json + 现有 tasks.json

• 支持 JSONC 注释（比较时忽略注释）

• 输入文件同时兼容 .json 与 .jsonc 后缀：找不到 team.settings.json 时自动尝试 team.settings.jsonc，两者都存在时 .json 优先

• 平台分版自动并入：任一输入文件都可按平台拆分，平台段插在扩展名前（win32→windows、linux→linux、darwin→osx），如 team.settings.json → team.settings.windows.json / team.settings.linux.json（.jsonc 变体同样支持）。插件检测当前系统，只把匹配平台的那份插到对应基础输入之后参与合并（优先级高于基础输入、低于下一个输入），其它平台的文件不参与；没有平台文件时行为与不带分版完全一致。可用 vscodeSettingsCombiner.platformInputs 关闭

• 输出文件头部自动加 // This file is generated by vscode-settings-combiner... 生成标记（可关闭）

• 文件变化自动重新合并（200ms 防抖，忽略对输出文件自身的写入，不会循环触发）

命名规则

建议 .gitignore：

.vscode/settings.json
.vscode/tasks.json
.vscode/backup.*

合并优先级

user > team.<platform> > team > settings.json（tasks 同理）：

1. 现有输出文件作为最低优先级基底参与合并——手工加进 settings.json 的配置会被保留吸收，只有与 team/user 冲突的键才会被覆盖；
2. team.*.json 覆盖输出文件中的同名键；
3. team.*.<platform>.json（当前平台分版）覆盖团队基础配置中的同名键；
4. user.*.json 优先级最高。

合并结果稳定收敛：写回后再次合并结果不变，不会抖动、不会反复弹窗。

合并规则

• settings：对象按键深合并，优先级高者覆盖低者；嵌套对象（如 files.exclude）按键合并不整体覆盖。
• tasks：
  • 顶层标量（version 等）高优先级方胜出；
  • tasks 数组按 label 合并：高层同名任务深合并到低层任务上（可只覆盖 command 一个字段，继承其余字段），新 label 的任务追加到末尾；
  • inputs 数组按 id 合并，规则同上。

快速上手

1. 在项目的 .vscode/ 目录创建两个文件（参考扩展详情页示例，或用 VSCode 的 JSON 补全直接写）：

   // .vscode/team.settings.json —— 团队统一配置
   {
     "editor.formatOnSave": true,
     "editor.tabSize": 2
   }
   

   // .vscode/user.settings.json —— 个人覆盖，优先级最高
   {
     "editor.tabSize": 4
   }
   

2. 重新加载窗口（Ctrl+Shift+P → "Developer: Reload Window"），.vscode/settings.json 自动生成。

3. 手动触发/验证：命令面板运行 VSCode Settings Combiner: Combine Config Files；日志在输出面板的 VSCode Settings Combiner 通道（能看到加载/跳过/写入记录）。

4. 已有 settings.json 时：内容与合并结果一致则不动；不一致默认直接覆盖（手工配置会被保留进合并结果），需要确认弹窗可开启 vscodeSettingsCombiner.warnDiff。

配置项

tasks.json 合并示例

// .vscode/team.tasks.json
{
  "version": "2.0.0",
  "tasks": [
    { "label": "build", "type": "shell", "command": "make build",
      "group": { "kind": "build", "isDefault": true } }
  ]
}

// .vscode/user.tasks.json —— 同名 label 只覆盖 command，继承 team 的 group
{
  "version": "2.0.0",
  "tasks": [
    { "label": "build", "command": "make build-fast" }
  ]
}

合并结果：build 任务使用 make build-fast 且保留默认构建分组。

注意事项

• 插件激活晚于 VSCode 首次读取配置，窗口打开的一瞬间仍是未合并状态，写入后立即生效（同类插件的共同局限）。
• 只处理 settings 与 tasks 两类文件；输入文件不存在时静默跳过，不会报错（日志中会记录 tried 文件名）。
• 输入文件一个都没有时：若工作区已存在 .vscode 目录（表示项目启用了该约定），会自动创建空的 settings.json / tasks.json 占位；没有 .vscode 目录的工作区不做任何事。
• .jsonc 变体只对输入文件生效；输出文件固定为 settings.json / tasks.json（VSCode 只认这两个名字）。形如 user.settings.jsonc.tmpl 的模板文件不会被读取，请先复制为 user.settings.jsonc。