VSCode工作区配置必须为项目根目录下的.vscode/settings.json文件，模板需手动复制并重命名；多根工作区应使用.code-workspace文件统一管理配置。
工作区配置模板到底该放在哪
VSCode 的工作区配置（.vscode/settings.json）是项目级的，不能靠“模板文件”自动复制生成——它必须真实存在于每个工作区根目录下。所谓“模板”，其实是你手动维护的一份参考配置，用以快速初始化新项目。
常见错误现象：settings.json.template 放在项目里但没重命名，VSCode 完全无视；或把模板扔进 $HOME/.vscode/，结果对任何项目都不生效。
- 工作区配置只认
.vscode/settings.json（路径必须小写、带点、在项目根目录） - 用户级配置在
$HOME/.vscode/settings.json，影响所有项目，但无法覆盖工作区配置 - 想复用？建议把常用配置存为 snippet 或用脚本一键生成：
cp ~/.vscode/templates/node-workspace.json .vscode/settings.json
哪些配置项适合放进工作区模板
工作区配置的核心价值是「让协作者开箱即用」，不是堆功能。重点锁定影响代码行为、格式、校验的硬性规则，而不是个人偏好类设置。
使用场景：团队协作、CI 一致性、新人快速上手。
- 必加：
"editor.formatOnSave": true、"editor.codeActionsOnSave": { "source.fixAll.eslint": true } - 推荐：
"files.trimTrailingWhitespace": true、"files.insertFinalNewline": true - 避免：
"workbench.colorTheme"、"terminal.integrated.fontSize"——这些属于个人 UI 偏好，不该污染工作区 - 注意：
"eslint.validate"已被弃用，新版 ESLint 插件只认"eslint.lintTask.enable"和"eslint.options"
为什么 workspaceSettings.json 有时不生效
最常踩的坑不是配置写错，而是 VSCode 没真正加载到这个工作区——尤其当你用命令行打开子目录、或从外部链接跳转时，它可能默认进了父文件夹甚至用户级上下文。
验证方法：按 Ctrl+Shift+P（macOS 是 Cmd+Shift+P），输入 Developer: Toggle Developer Tools，在 Console 里打 JSON.stringify(vscode.workspace.getConfiguration().get('editor.formatOnSave'))，看返回值是否匹配你预期。
- 检查当前窗口右下角是否有「[Workspace]」标识，没有说明你不在工作区上下文中
-
code .必须在项目根目录执行，code src/会丢失.vscode/ - 多根工作区（
.code-workspace文件）中，.vscode/settings.json会被忽略，改用settings字段声明 - 插件未启用时，其相关配置（如
prettier.*）即使写了也无效果
用 .code-workspace 管理多个模板更靠谱
单项目用 .vscode/settings.json，但如果你常建同类型项目（比如多个 Next.js 应用），不如直接维护几个 .code-workspace 文件——它本身就能带完整工作区配置、文件夹列表、甚至任务定义。
性能影响极小，但可读性和复用性远超零散 JSON 模板。
- 新建
next-template.code-workspace，内容含"folders"（可填占位路径如"./__project__"）和"settings"块 - 用脚本替换占位符并重命名：
cp next-template.code-workspace my-app.code-workspace && sed -i 's/__project__/my-app/g' my-app.code-workspace - 双击打开该文件，VSCode 自动识别为多根工作区，且所有配置立即生效
- 比复制粘贴
.vscode/更干净——没有残留的tasks.json或调试配置干扰
真正麻烦的从来不是怎么写配置，而是怎么确保它被加载、被理解、被继承。每次新建项目时少一次手动检查 .vscode 是否存在，就少一个协作者报「格式化不生效」的问题。
