VSCode 配置机制完整笔记
一、.vscode 目录概述
.vscode 是 VS Code 的项目级配置目录，定义"当 VS Code 打开这个项目时，该如何表现"。
常见文件结构
.vscode/
├── settings.json # 工作区设置（覆盖用户全局设置）
├── extensions.json # 推荐安装的扩展列表
├── launch.json # 调试配置
├── tasks.json # 自定义任务
└── snippets/ # 代码片段目录
二、配置层级与覆盖机制
三层架构（优先级由低到高）
VS Code 默认设置
↓
用户级设置（~/settings.json）
↓
工作区设置（.vscode/settings.json）← 项目级，优先级最高
关键区别
示例对比
settings.json（增量）
// 用户级：a=1, b=2, c=3, d=4, e=5
// 项目级写：{"b": 20}
// 结果：a=1, b=20, c=3, d=4, e=5（继承+覆盖）
extensions.json（全量）
// 用户级：安装了 a,b,c,d
// 项目级写：{"recommendations": ["a","b"]}
// 结果：只推荐 a,b（不会推荐 c,d）
三、配置存储位置
用户级配置
项目级配置
- 位置：
.vscode/ 目录下 - 作用范围：仅当前项目
- 版本控制：应提交到 Git，确保团队一致
四、扩展管理
用户级 vs 项目级
扩展推荐配置
{
"recommendations": ["dbaeumer.vscode-eslint", "esbenp.prettier-vscode"],
"unwantedRecommendations": ["some.extension.to.disable"]
}
多项目扩展隔离方案
场景：项目A用a,b,c，项目B用d,e,f，其他项目用a,b,c,d
五、跨平台路径处理
核心原则
能用相对不用绝对，能用变量不用字符串
内置变量
正确 vs 错误示例
// ❌ 错误：硬编码绝对路径
"python.defaultInterpreterPath": "C:/Users/123/project/venv/bin/python"
// ✅ 正确：使用变量
"python.defaultInterpreterPath": "${workspaceFolder}/venv/bin/python"
"python.analysis.extraPaths": ["${userHome}/.local/lib/python"]
特殊情况处理
如果路径完全无关（如 Windows D:\project1\123 vs macOS Documents/project1/123）：
六、VS Code 设置同步
同步内容
- ✅ 用户级
settings.json - ✅ 扩展列表（自动重新安装）
- ✅ 键盘快捷键
- ✅ 用户级代码片段
- ✅ UI 状态
不同步内容
- ❌ 项目级
.vscode/ 目录（需 Git 管理） - ❌ 扩展的本地数据/缓存
分工明确
七、最佳实践总结
1. 配置原则
- 项目级（
.vscode/）：放团队共享、通用、跨平台的配置 - 用户级（
~/settings.json）：放个人偏好、系统特定的配置
2. 路径原则
- 优先使用
${workspaceFolder}（项目内） - 其次使用
${userHome}（用户目录） - 避免硬编码盘符（如
D:\、/Volumes/）
3. 扩展原则
- 项目必需的扩展 →
extensions.json 推荐 - 个人辅助扩展 → 用户级安装，不同步到项目
4. 调试/任务原则
- 通用任务 →
.vscode/tasks.json（全量定义） - 个人调试习惯 → 用户级
launch.json
八、快速参考命令