VSCode 的每一项设置都来自四个来源之一： 默认值（Default）、用户级（User）、工作区（Workspace）、文件夹（Folder）。 它们从下到上覆盖——越靠近你正在编辑的文件，优先级越高。 理解这条规则，你就再也不会问「为什么我改了设置没生效」。

配置文件实际位置

真实场景：一个 fontSize 的旅行

# Layer 1 · Default
"editor.fontSize": 12      # VSCode 出厂默认

# Layer 2 · User （你的全局偏好）
# ~/Library/.../User/settings.json
"editor.fontSize": 14      # 你眼睛舒服的字号 → 覆盖 Default

# Layer 3 · Workspace （这个项目要求）
# projectA/.vscode/settings.json
"editor.fontSize": 16      # 团队 README 演示用大字号 → 覆盖 User

# Layer 4 · Folder （multi-root 内的子 folder）
# projectA/legacy-module/.vscode/settings.json
"editor.fontSize": 13      # 旧模块代码密 → 覆盖 Workspace

# 最终生效值：13（最上层）

Settings UI 是给新手的「引导轮」，等你能直接读 JSON 就该把它扔掉。 理由很硬：所有真相都在 JSON 里， UI 只是 JSON 的一种渲染。

UI 与 JSON 的对比

打开 JSON 的三种方式

# 方式 A · 命令面板（推荐）
⌘⇧P → Preferences: Open User Settings (JSON)
⌘⇧P → Preferences: Open Workspace Settings (JSON)
⌘⇧P → Preferences: Open Folder Settings (JSON)   # multi-root 才有
⌘⇧P → Preferences: Open Default Settings (JSON)  # 只读 · 看默认值

# 方式 B · 从 UI 切到 JSON
# Settings UI 右上角有个「{ }」图标 → 直接跳到对应 JSON

# 方式 C · 直接打开文件
$ code ~/Library/Application\ Support/Code/User/settings.json

JSON 编辑时的 IntelliSense

在 settings.json 里按 ⌘空格 触发补全，VSCode 会列出所有可用设置项 —— 包括每一个扩展贡献的设置。 光标停在键名上还会浮出文档说明。这是 UI 永远做不到的「全局可索引」。

// settings.json — 输入时享受 IntelliSense
{
  "editor.fo|         // ← 在此 ⌘空格，下拉列出：
  //   editor.fontFamily
  //   editor.fontLigatures
  //   editor.fontSize
  //   editor.fontVariations
  //   editor.fontWeight
  //   editor.formatOnPaste
  //   editor.formatOnSave
  //   editor.formatOnType
  //   ...
}

.vscode/ 目录是项目级配置的官方约定位置。 把它 commit 进 git，新人 clone 仓库时就自动继承团队规范—— 不用再写"请把 tab 改成 2 个空格"的 README。

.vscode/ 目录三件套

团队 .vscode/settings.json 模板

// .vscode/settings.json — 通用前后端项目
{
  // === 缩进与格式 ===
  "editor.tabSize": 2,
  "editor.insertSpaces": true,
  "editor.detectIndentation": false,
  "files.eol": "\n",
  "files.insertFinalNewline": true,
  "files.trimTrailingWhitespace": true,

  // === 格式化 ===
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "[python]": {
    "editor.defaultFormatter": "charliermarsh.ruff",
    "editor.tabSize": 4
  },
  "[go]": {
    "editor.defaultFormatter": "golang.go",
    "editor.insertSpaces": false   // Go 用 tabs
  },

  // === 隐藏噪声 ===
  "files.exclude": {
    "**/.git": true,
    "**/node_modules": true,
    "**/__pycache__": true,
    "**/dist": true
  },
  "search.exclude": {
    "**/node_modules": true,
    "**/dist": true,
    "**/coverage": true,
    "pnpm-lock.yaml": true
  },

  // === TypeScript 项目特化 ===
  "typescript.tsdk": "node_modules/typescript/lib",
  "typescript.preferences.importModuleSpecifier": "non-relative",

  // === ESLint / Prettier 自动修复 ===
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit",
    "source.organizeImports": "explicit"
  }
}

.vscode/extensions.json 推荐扩展

// .vscode/extensions.json
{
  // 新人 clone 后会被提示"是否安装这些扩展"
  "recommendations": [
    "esbenp.prettier-vscode",
    "dbaeumer.vscode-eslint",
    "editorconfig.editorconfig",
    "streetsidesoftware.code-spell-checker",
    "eamodio.gitlens"
  ],

  // 不推荐的扩展（可选）— 装了会弹警告
  "unwantedRecommendations": [
    "hookyqr.beautify",            // 与 Prettier 冲突
    "ms-vscode.vscode-typescript-tslint-plugin"  // TSLint 已废弃
  ]
}

什么该 commit、什么该 ignore

配合 .editorconfig

团队成员用不同编辑器（Vim / JetBrains / Cursor）时，.vscode/settings.json 只覆盖 VSCode。 用 .editorconfig 做更基础的规范——它被几乎所有主流编辑器原生或插件支持。

# 项目根 .editorconfig
root = true

[*]
indent_style = space
indent_size = 2
end_of_line = lf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true

[*.{py,go}]
indent_size = 4

[Makefile]
indent_style = tab

就算坚定走 JSON 派，Settings UI 顶部那个搜索框也值得花 5 分钟学—— 它支持@ 前缀过滤器，是查阅默认值、审视改过哪些、按语言/功能筛选的利器。

六个常用过滤器

用户级 settings.json 必备调优 — 我的 10 项

// ~/Library/.../User/settings.json — 装好就调，受益 21 天
{
  // 1. 字号 + 行高
  "editor.fontSize": 14,
  "editor.lineHeight": 1.6,

  // 2. 字体连字（→ ≠ <= 等组合字符）
  "editor.fontFamily": "JetBrains Mono, Menlo, monospace",
  "editor.fontLigatures": true,

  // 3. 关掉烦人的小地图
  "editor.minimap.enabled": false,

  // 4. Tab 在最近编辑顺序而不是位置顺序中切换
  "workbench.editor.enablePreview": false,   // 单击打开就 pin，不再被覆盖

  // 5. 自动保存（防丢工作）
  "files.autoSave": "onFocusChange",

  // 6. 终端字体跟编辑器一致 + 滚动行数加大
  "terminal.integrated.fontFamily": "JetBrains Mono",
  "terminal.integrated.scrollback": 10000,

  // 7. 平滑光标移动（视觉舒适）
  "editor.cursorBlinking": "smooth",
  "editor.cursorSmoothCaretAnimation": "on",

  // 8. 文件树缩进加大 + 启用嵌套
  "workbench.tree.indent": 16,
  "explorer.fileNesting.enabled": true,

  // 9. 不要每次问"是否信任此工作区"
  "security.workspace.trust.untrustedFiles": "open",

  // 10. Git 自动 fetch + 显示 inline blame
  "git.autofetch": true,
  "git.confirmSync": false
}

今天的三个 Lab 把今天的所有内容串起来—— 验证优先级、建立团队模板、审视个人 dotfile。

Lab 1 — 三层覆盖实验

用 fontSize 这个肉眼可见的设置，验证 User → Workspace 的覆盖关系。

# 1. 准备工作区
$ cd ~/vscode-day01 && code .

# 2. 在 User settings.json 设置一个明显字号
⌘⇧P → Preferences: Open User Settings (JSON)
# 添加：
  "editor.fontSize": 14

# 3. 切到 Workspace 层覆盖
⌘⇧P → Preferences: Open Workspace Settings (JSON)
# 该命令会自动创建 .vscode/settings.json，添加：
  "editor.fontSize": 22

# 4. 观察：编辑器字号立刻变成 22

# 5. 验证 UI 显示
⌘⇧P → Preferences: Open Settings (UI)
# 搜 fontSize 看到右边显示「Modified in: Workspace」

# 6. 删掉 .vscode/settings.json 的 fontSize
# 编辑器立刻回到 14（User 层）

预期观察：看到一项设置时，UI 会标注它的覆盖来源（User / Workspace / Default Override / 等）——这是排查"为什么改了不生效"的关键信号。

Lab 2 — 给项目建一份 .vscode/ 模板

把上面 §03 的模板真正落地到一个测试项目里。

# 1. 创建测试项目
$ mkdir ~/vscode-day03-team && cd ~/vscode-day03-team
$ git init
$ mkdir .vscode

# 2. 创建 settings.json（拷上面模板的简化版）
$ cat > .vscode/settings.json <<'EOF'
{
  "editor.tabSize": 2,
  "editor.insertSpaces": true,
  "editor.formatOnSave": true,
  "files.eol": "\n",
  "files.insertFinalNewline": true,
  "files.trimTrailingWhitespace": true,
  "files.exclude": {
    "**/node_modules": true,
    "**/dist": true
  }
}
EOF

# 3. 创建 extensions.json 推荐扩展
$ cat > .vscode/extensions.json <<'EOF'
{
  "recommendations": [
    "esbenp.prettier-vscode",
    "editorconfig.editorconfig",
    "streetsidesoftware.code-spell-checker"
  ]
}
EOF

# 4. 创建 .editorconfig 兜底
$ cat > .editorconfig <<'EOF'
root = true

[*]
indent_style = space
indent_size = 2
end_of_line = lf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true
EOF

# 5. commit 后用 code . 打开
$ git add . && git commit -m "chore: add VSCode workspace config"
$ code .

预期观察：VSCode 右下角应该弹一个 toast「This workspace has extension recommendations」——这就是 extensions.json 在工作。

Lab 3 — 审视你的 User settings

用 @modified 过滤器看看你自己改过多少项，理清「真正在用」和「忘了为什么改」。

1. ⌘⇧P → Preferences: Open Settings (UI)
2. 在顶部搜索框输入 @modified
3. 列表里会显示所有你偏离默认值的设置项
4. 对每一项问自己："我为什么改了它？"
   • 能说出原因 → 保留
   • 不记得 → 改回默认值（点右侧齿轮 → Reset Setting）
5. 切到 JSON 视图（⌘⇧P → Open User Settings (JSON)）
6. 把剩下的项按主题分组 + 加注释（参考 §04 的"必备调优 10 项"格式）

1. VSCode 设置的四层架构是什么？它们的优先级从低到高是什么顺序？
2. User 层和 Workspace 层在物理文件位置上分别是什么？
3. 为什么直接编辑 settings.json 比用 Settings UI 更高效？至少举出 3 个理由。
4. .vscode/settings.json 和 .editorconfig 的分工是什么？为什么需要两份？
5. @modified / @lang:python / @ext:esbenp.prettier-vscode 三个过滤器分别在什么场景用？