VS Code 如何导出并共享最小化的工作区配置

共享 VS Code 项目配置时，不要把自己的整份 User Settings 导出给团队。更稳妥的做法是：在当前项目的 Workspace 范围筛出真正需要的设置，只保留到 .vscode/settings.json，再用 .vscode/extensions.json 提供必要扩展推荐。这样既能统一项目行为，也不会把主题、字体、私人路径和账号相关偏好混进去。

官方设置文档：https://code.visualstudio.com/docs/configure/settings

VS Code 官方文档说明，Workspace Settings 只对当前项目生效，并覆盖 User Settings；单文件夹工作区会把这些设置保存在项目根目录的 .vscode 文件夹中。因此这里所谓“导出”，本质上是整理并提交这两份项目文件，而不是使用一个打包导出按钮。

先判断哪些内容值得共享

我通常先把候选配置分成两类：能改变项目协作结果的留下，只影响个人观感的删除。下面这张表可以快速做第一轮判断。

步骤一：从 Workspace 范围找出真正改过的设置

1. 打开项目文件夹，确认资源管理器顶部显示的是项目根目录。
2. 使用菜单 File → Preferences → Settings；macOS 也可以从应用设置入口打开 Settings。
3. 在设置界面顶部切换到 Workspace 标签，不要停留在 User。
4. 在搜索框输入 @modified，只查看当前 Workspace 范围中与默认值不同或已经显式写入 JSON 的项目。

完成后，界面应该同时满足两个可见条件：Workspace 标签处于选中状态，结果列表只剩少量修改项。如果仍然看到主题、字体等大量个人配置，先检查自己是否误停留在 User 标签。

步骤二：把候选项压缩成最小 settings.json

按 Ctrl+Shift+P（macOS 为 Cmd+Shift+P）打开命令面板，运行 Preferences: Open Workspace Settings (JSON)。单文件夹项目会打开 .vscode/settings.json。

一个精简示例可以只保留以下三类行为。JSON 本身不支持注释，因此字段含义放在代码块后说明。

{
  "editor.formatOnSave": true,
  "files.exclude": {
    "**/.cache": true
  },
  "[markdown]": {
    "editor.wordWrap": "on"
  }
}

editor.formatOnSave 统一保存时格式化入口；files.exclude 隐藏项目不需要直接浏览的缓存目录；语言块只约束 Markdown。这里没有主题、字号、终端程序或用户目录。保存后，资源管理器中应出现 .vscode/settings.json，Settings 的 Workspace 标签也能回显这些值。

如果团队格式化规则依赖 Prettier、ESLint 或其他工具，优先把真正的规则写进项目自身配置文件，例如 .prettierrc 或 eslint.config.js。工作区设置只负责启用一致入口，避免把所有规则塞进编辑器专属文件。

步骤三：把必要扩展写成推荐而不是强制清单

打开命令面板，运行 Extensions: Configure Recommended Extensions (Workspace Folder)。在单文件夹工作区中，VS Code 会创建 .vscode/extensions.json。每个扩展使用 publisher.extension 形式的标识。

{
  "recommendations": [
    "dbaeumer.vscode-eslint",
    "esbenp.prettier-vscode"
  ]
}

示例表示项目建议使用 ESLint 和 Prettier，但不会替成员静默安装。接收者首次打开工作区时可以看到推荐提示，也可以运行 Extensions: Show Recommended Extensions 手动查看。

步骤四：用版本控制预览并排除私人信息

打开左侧 Source Control 视图，逐个查看 .vscode/settings.json 和 .vscode/extensions.json 的差异。不要看到“只有两个文件”就直接提交，还要逐项排除以下内容：

• 用户主目录、磁盘盘符和本机 SDK 绝对路径；
• 访问令牌、账号、邮箱、代理凭据和私有服务器地址；
• 只对个人有意义的主题、字体、缩放比例和窗口布局；
• 团队没有采用的实验功能或组织策略项；
• 已经由项目配置文件管理、无需重复声明的规则。

检查完成后，变更列表最好只保留这两份配置文件，而且每个键都能回答“它解决了哪个项目协作问题”。这就是最小化的核心：不是追求文件行数最少，而是每一行都能被团队解释和维护。

步骤五：让接收者核对配置是否生效

另一位成员拉取代码后，用 File → Open Folder 打开项目根目录，然后按下面顺序验收：

1. 打开 Settings，切换到 Workspace，确认共享键显示为工作区值；
2. 打开 Extensions 视图，运行 Extensions: Show Recommended Extensions，确认能看到项目推荐；
3. 修改一个受影响的文件并保存，确认格式化或换行行为符合预期；
4. 检查 Source Control，确认没有因为编辑器自动生成额外私人配置。

如果配置没有生效，先确认打开的是项目根目录，而不是单独打开某个文件。还要注意设置优先级：Workspace 设置通常覆盖 User 设置，但语言专属设置和组织策略可能有更高优先级。

多根工作区改用 .code-workspace 文件

当一个窗口中包含多个根文件夹时，Workspace 设置位于 .code-workspace 文件中，而不是统一塞进某个根目录的 .vscode/settings.json。扩展推荐也可以写在该文件的 extensions.recommendations 下。

{
  "folders": [
    { "path": "frontend" },
    { "path": "backend" }
  ],
  "settings": {
    "editor.formatOnSave": true
  },
  "extensions": {
    "recommendations": [
      "dbaeumer.vscode-eslint"
    ]
  }
}

这里使用相对路径，成员把仓库放在不同目录也能打开。若某个根文件夹需要独立配置，Folder Settings 可以覆盖工作区级设置。

Settings Sync 能代替项目配置吗

不能。Settings Sync 适合在自己的设备之间同步用户级设置、快捷键和片段；它不是把项目规则交给团队的渠道。官方文档还明确说明 Workspace tasks 不会被 Settings Sync 同步。项目级配置仍应放在仓库中，由代码评审和版本历史管理。

常见问题

.vscode 文件夹要不要整体提交？

不建议一概整体提交。先逐个文件判断是否与团队协作有关。本文场景通常只需要 settings.json 和 extensions.json；调试与任务配置应在团队确实共享同一流程时再加入。

为什么同事打开项目后没有扩展推荐？

先确认文件位于 .vscode/extensions.json，扩展标识使用完整的 publisher.extension 格式，并让对方运行 Extensions: Show Recommended Extensions 查看。若对方关闭了推荐通知，列表仍可手动打开。

怎样快速找出不该共享的设置？

优先搜索路径、代理、终端、主题、字体、账号和令牌相关键，再检查每一项是否能在另一台机器上直接使用。任何需要成员改成本机值的设置，都不适合原样提交。

整理完成后，团队拿到的是一份可解释、可审阅、可回滚的项目配置，而不是某个人编辑器环境的镜像。以后新增设置也沿用同一原则：先说明协作问题，再决定是否进入 Workspace 范围。