VS Code

VS Code 工作区与可信执行参考图从安装通道进入工作区，再让 Profile、同步、任务、调试和扩展分别落在正确的信任与治理边界内。高清原图

同一个仓库为什么在两台开发机上表现不同

一次常见的接手现场是：仓库在 CI 中通过，开发者甲点击任务也能运行，开发者乙打开后却找不到任务，断点始终灰色。两人的源码和 Node.js 版本完全一致，差异来自甲打开的是仓库根目录，乙打开的是 src 子目录；甲的用户设置和扩展还悄悄补齐了项目没有声明的行为。继续重装扩展只会改变现场，无法解释故障。

VS Code 窗口同时承载工作区设置、扩展、终端、任务、调试器和账号同步。排障时先钉住三个对象：窗口把哪个目录当作工作区，配置保存在用户、Profile 还是仓库，任务与扩展最终在哪个进程和身份下执行。远程窗口还会把运行时、扩展和凭证位置再次拆开，具体连接模型可继续阅读 VS Code Remote SSH 与 WSL；复杂的 attach、路径映射与调试协议由 任务、运行与调试配置 承接。

下面先在本地桌面版建立一条不依赖第三方扩展的证据链：系统终端运行源码，VS Code 从同一根目录打开，再由受审查的任务和调试配置运行同一个入口。Profiles、Settings Sync 和企业策略随后各自落到个人隔离、个人连续性与组织强制约束上，避免把四种配置机制混成一份“能用就行”的设置。

先确认运行时和安装身份

实验机需要普通用户写权限，并已安装项目允许的 Node.js。先在系统终端确认：

node --version

预期输出一个项目允许的 Node.js 版本。若命令不存在，先修复系统运行时与 PATH；语言扩展可以提供编辑体验，却不能替系统安装一个可供任务和 CI 共同使用的 Node.js。随后记录 code --version 的版本、提交标识和架构，后面的每个结论都应能回到这两个命令，而不是只依赖界面截图。

先选发布通道和安装渠道

Stable 与 Insiders 不是主备版本

微软的 VS Code 更新说明 当前把 Stable 作为持续更新通道；Insiders 更适合验证即将发布的功能、确认上游修复或提前测试扩展兼容性。它可以与 Stable 并存，命令通常分别是 code 与 code-insiders，用户数据目录也分开；这使它适合作为升级验证环境，却不等于稳定版的自动回滚副本。

团队可以保留一个代表性项目，在 Insiders 上提前跑导入、任务、调试和核心扩展验证。出现阻断时回到 Stable，并把问题定位为“编辑器通道差异”，而不是立刻改项目配置。不要让所有成员长期追随 Insiders，再靠口头约定处理每日变化。

Windows 的三种入口

官方 Windows 安装文档 将 User Setup、System Setup 和 ZIP 作为三个不同入口。多数单人开发机选择 User Setup：它安装在当前用户目录，不要求管理员权限，更新链路最平滑。共享实验机、受管终端或确实需要所有 Windows 用户共用时才选择 System Setup；安装和产品更新都可能需要提升权限。

ZIP 适合无安装权限、隔离验证或需要 Portable Mode 的场景。它的代价是每个版本都要手工替换，并自行管理快捷方式、PATH 和数据目录。Portable Mode 只适用于官方列出的归档或应用包形态，不能在 Windows User / System 安装上靠手工创建 data 目录模拟。ZIP 解压目录与 data 目录应分离备份；不能把编辑器二进制、扩展和业务代码混在仓库里。

安装后关闭并重新打开终端，再验证：

code --version
code --status

code --version 预期至少输出版本、提交标识和架构。code --status 只在已有 VS Code 实例运行时提供进程与环境诊断；实例尚未启动时会提示先启动 Code，而且该路径仍可能返回退出码 0，所以自动采集必须同时检查输出是否真的包含进程信息。若 code 找不到，先检查安装器是否写入 PATH、终端是否重启，以及当前命令是否被旧 ZIP 目录抢先解析：

Get-Command code -All

macOS 与 Linux

macOS 常见入口是下载应用包并拖入 Applications，然后在命令面板执行 Shell Command: Install 'code' command in PATH。Linux 优先使用官方 .deb 或 .rpm 及其配置的软件源，让后续更新仍由包管理器负责；Snap、社区仓库和手工 TAR.GZ 必须分别记录维护者、自动更新语义与回退方式。

架构师关心的不是“哪条安装命令最短”，而是渠道是否可追溯、能否统一升级、是否支持回退、是否符合终端管理策略。团队资产清单至少记录产品通道、安装类型、版本、扩展源和更新责任人。

用工作区定义项目边界

先在系统终端创建一个最小目录：

mkdir vscode-workspace-lab
cd vscode-workspace-lab
mkdir src

创建 src/app.js：

const message = "workspace-ok";
console.log(message);

先证明项目本身可运行：

node src/app.js

预期输出：

workspace-ok

然后从项目根打开：

code .

VS Code 的 workspace 是一个窗口中打开的一个或多个目录。单目录工作区把 .vscode/settings.json、.vscode/tasks.json 和 .vscode/launch.json 放在项目根；多根工作区由 .code-workspace 文件列出多个目录，并可拥有工作区级配置。它不是 Maven、Gradle 或 npm 的项目模型，不能替代构建文件。

打开错误目录会产生一串相似症状：搜索范围过大、任务的 ${workspaceFolder} 指错、调试器找不到程序、扩展扫描父目录、版本控制根混乱。判断方法不是反复重装扩展，而是先在集成终端确认：

pwd
node src/app.js

Windows PowerShell 可用 Get-Location 代替 pwd。终端位置、Explorer 根节点和 CLI 成功目录应指向同一项目根。

把配置放到正确层级

用户设置影响当前 VS Code 用户的所有窗口；工作区设置只影响当前项目，并覆盖用户设置；多根工作区还可以为每个 folder 设置更具体的值。团队共享的配置应满足两个条件：与项目语义相关，而且不依赖个人机器。

创建 .vscode/settings.json：

{
  "files.eol": "\n",
  "files.insertFinalNewline": true,
  "editor.formatOnSave": false,
  "files.exclude": {
    "**/.cache": true
  }
}

这里故意不指定本机 Node.js 绝对路径、不写代理地址、不打开全局格式化。files.eol 和末尾换行是可审查的项目约束；formatOnSave 先关闭，是为了避免成员安装不同 formatter 后产生大面积无关 diff。格式化规则应由项目工具配置和 CI 共同定义，而不是只靠某个人的用户设置。

敏感或机器相关值不要进入 .vscode/settings.json、.code-workspace、tasks.json 或 launch.json：

不写真实 token、密码、Cookie、内网域名和生产 URL。不写 C:\Users\某人\...、/Users/某人/... 等绝对路径。不把 SSH 私钥、云凭证或生产 kubeconfig 通过环境变量明文提交。

不假设 ${env:NAME} 就等于安全；变量名可提交，实际值必须来自操作系统凭证链或受控 Secret 注入。

用 Profile 隔离个人工具面

Profiles 把设置、快捷键、代码片段、任务、扩展和 UI 状态组织成一组用户级定制。它适合隔离“Java 维护”“前端排障”“干净验证”等个人工作面，不适合代替仓库中的团队基线。

在 Profiles 编辑器中创建 vscode-lab-clean，选择 Empty Profile，只安装实验确实需要的扩展。也可以从命令行启动：

code . --profile "vscode-lab-clean"

若该名称不存在，VS Code 会创建空 Profile。验证时比较默认 Profile 与空 Profile：同一个 node src/app.js 应都成功，而语言提示、格式化器和侧栏可能不同。这能把“项目不能运行”和“个人扩展组合异常”分开。

Temporary Profile 会在窗口关闭后删除，适合复现插件冲突。导出的 Profile 不包含部分机器相关设置，但仍可能泄露扩展清单、工作习惯和组织技术栈；分享前必须审查内容。Profile 也没有继承链，复制后两份配置会独立演化，不能把它当成企业策略分发系统。

启用 Settings Sync，但不要把它当团队配置

按照 Settings Sync 的账号入口，通过 Accounts 或 Manage 菜单选择 Backup and Sync Settings...，使用受组织允许的 Microsoft 或 GitHub 账号登录，再选择要同步的类别。第一次启用时先审查云端已有数据，避免把旧扩展和旧设置直接合并进新机器。

建议个人先同步快捷键、用户片段和经审查的 Profiles，再决定是否同步扩展。机器作用域设置默认不参与同步；远程 SSH、Dev Container 和 WSL 窗口中的扩展也不由本地 Settings Sync 自动覆盖。出现“本机有扩展、远端没有”时，这通常是设计边界，不是同步损坏。

最小验证分两步：先修改一个无敏感信息的用户设置并确认同步状态无错误；再在第二台受控设备或独立测试 Profile 中拉取，确认该设置出现。不能只看账号头像就认定同步成功。

关闭同步时要区分“停止当前设备同步”和“清除云端数据”。离职、账号迁移或组织切换时应完成账号退出、云端数据处置和本机凭证清理；单纯卸载 VS Code 不会自动完成这些治理动作。

在信任之前只阅读代码

第一次打开陌生目录时保持 Workspace Trust 提供的 Restricted Mode。此时 VS Code 会限制终端、任务、调试、部分工作区设置和扩展，让你先检查可执行面：

.vscode/tasks.json
.vscode/launch.json
.vscode/settings.json
package.json 及生命周期脚本
构建脚本、环境加载脚本、二进制文件
工作区推荐扩展

确认来源、提交和脚本后，再通过 Workspaces: Manage Workspace Trust 信任准确的项目目录。不要为了少一次提示而信任用户主目录、下载目录或包含大量仓库的共同父目录；子目录可能继承父目录信任，这会扩大执行边界。

Restricted Mode 是额外防线，不是沙箱。扩展通常能读工作区、发起网络请求、启动外部进程，并可能访问工作区之外的用户文件。官方明确指出，恶意扩展可以忽略 Restricted Mode。信任仓库与信任扩展发布者是两次独立决策，不能互相替代。

配置一个可审查的任务

创建 .vscode/tasks.json：

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "verify:workspace",
      "type": "process",
      "command": "node",
      "args": ["src/app.js"],
      "options": {
        "cwd": "${workspaceFolder}"
      },
      "problemMatcher": []
    }
  ]
}

选择 Tasks: Run Task，运行 verify:workspace。预期终端输出 workspace-ok，任务退出码为 0。这里使用 process 而不是拼接 Shell 字符串，参数边界更清楚；真实项目仍应优先调用仓库已有的 npm run verify、Maven Wrapper 或 Gradle Wrapper，避免 IDE 与 CI 维护两套业务命令。

任务能执行任意程序。代码审查必须把 tasks.json 当作脚本入口，重点看 command、args、options.env、cwd、dependsOn 和后台任务。不要将真实密码直接写在 options.env，也不要把“任务能运行”误判成项目构建正确。

跑通最小调试

创建 .vscode/launch.json：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug workspace lab",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/src/app.js",
      "cwd": "${workspaceFolder}",
      "skipFiles": ["<node_internals>/**"]
    }
  ]
}

在 console.log(message) 行设置断点，选择 Debug workspace lab 后启动。预期调试器停在断点，Variables 中 message 的值是 workspace-ok；继续运行后 Debug Console 或终端输出同一文本并正常退出。

这个验证同时证明了四件事：工作区根正确、Node.js 可被 VS Code 找到、内置 JavaScript 调试器可启动目标进程、源码与运行文件一致。若 CLI 成功而调试失败，先比较 program、cwd、环境变量和 VS Code 进程继承到的 PATH，不要先删除整个用户配置。

清理、重置与回滚

最小实验的项目内清理是删除 .vscode/ 和实验目录；若这些文件已经提交，则通过正常 Git 变更回滚，不用系统删除命令越过版本历史。Profile 测试结束后，在 Profiles 编辑器删除临时 Profile 或执行 Developer: Reset Workspace Profiles Associations 解除目录关联。

卸载产品时按安装渠道处理：Windows Installer 通过系统应用卸载，ZIP 删除解压目录，Linux 使用原包管理器，macOS 删除应用。官方 卸载文档 说明，完整重置还需要另行删除用户数据目录和扩展目录；这会丢失所有设置与扩展，必须先备份并确认 Settings Sync 状态。

升级回滚优先使用通道隔离：保持 Stable，单独用 Insiders 或受控测试机验证。不要覆盖安装目录后继续复用未经验证的扩展状态。若问题只在某个扩展版本出现，先禁用扩展并用 Empty Profile 复现，再按照 扩展与插件治理 处理版本准入与回退。

接入真实项目

真实项目接入遵循“CLI 是事实源，IDE 是编排入口”。先从干净检出运行仓库规定的安装、构建和测试命令，再让 VS Code 调用同一入口。推荐只提交与项目一致的文件：

.vscode/
  settings.json
  tasks.json
  launch.json
  extensions.json
docs/
  development.md

settings.json 放最少项目差异，tasks.json 编排稳定脚本，launch.json 描述可复现调试入口，extensions.json 只推荐提升体验的扩展。项目必须在没有推荐扩展时仍可通过 CLI 构建；否则扩展已经成为未声明的构建依赖。

多根仓库只有在确实需要把多个独立根放入一个窗口时才使用 .code-workspace。路径优先相对化，并明确哪个 folder 提供任务与调试目标。不要把开发者本机任意目录、家庭目录或凭证目录加入共享 workspace。

常用提效路径

把高频操作收敛为少量命令入口：code . 从正确根打开；Command Palette 查动作；Quick Open 查文件；Search 在工作区内查文本；Tasks 调用仓库脚本；Run and Debug 复用命名配置。提效来自减少上下文切换和保持入口一致，不是安装更多扩展。

对大型仓库，先排除真正的生成目录、缓存和大制品，再观察搜索和文件监听表现。不要为了“变快”排除源码、测试或构建描述文件。排除规则会改变可见性和索引范围，应与仓库结构一起评审。

每次 VS Code 或核心扩展升级后，用同一组烟雾测试：打开正确根、运行 CLI、运行任务、命中断点、检查格式化 diff、确认 Settings Sync 状态。五分钟的固定验证比发生故障后清空所有缓存更便宜。

从现象回到原因

code . 打开的不是预期版本

界面版本与团队基线不一致，或 Stable / Insiders 配置混在一起。 执行 code --version、code-insiders --version，并在 Windows 用 Get-Command code -All 查看解析顺序。 旧 ZIP 目录抢占 PATH、快捷方式指向另一安装、终端尚未刷新环境。 保留一个明确的 Stable 入口，移除失效 PATH，重开终端；Insiders 使用独立命令。 版本、提交和架构符合资产清单，打开项目后任务仍输出 workspace-ok。

集成终端找不到 Node.js，但系统终端可以

外部终端 node --version 成功，VS Code 终端失败。 完全退出并重启 VS Code，比较两个终端的 PATH 与 Get-Command node / which node。 VS Code 在运行时尚未继承新的环境变量，或 Profile / Shell 初始化不同。 从已具备正确环境的终端运行 code .，修正 Shell 初始化；不要在仓库提交个人 Node.js 绝对路径。 集成终端和任务都能运行 node src/app.js。

任务被阻止或列表为空

Tasks: Run Task 要求信任，或目标任务没有出现。 查看状态栏是否为 Restricted Mode，检查 JSON 语法和当前 workspace 根。 陌生项目尚未信任、打开了源码子目录、tasks.json 不在当前工作区配置位置。 先审查可执行文件，再信任准确目录；把任务放回正确的 .vscode 或多根 workspace 配置。 任务可见且输出和 CLI 相同。

断点灰色或从不命中

程序运行结束，但断点显示未绑定。 确认调试配置实际启动的 program、工作目录和源码文件；查看 Debug Console。 打开了错误根、运行的是构建产物、源码映射不匹配，或目标进程由另一命令启动。 先回到前述直接运行源码的最小配置，再逐步接入构建产物和 source map。 断点绑定，message 值可见。复杂路径映射转交调试治理文章。

同步后设置反复变化

本机修改被另一设备覆盖，或扩展不断安装、禁用。 打开 Settings Sync 活动与冲突视图，核对当前 Profile、账号和同步类别。 多台设备同时修改同一用户配置、误登录个人账号、把插件状态当团队基线。 暂停同步，确定权威副本，手工合并后重新启用；团队规则回到仓库和组织策略。 第二设备只获得预期类别，项目配置不依赖账号同步。

Restricted Mode 仍不能消除扩展风险

团队认为“不信任工作区”就可以安全安装任意扩展。 查看扩展发布者、许可证、签名、更新历史、执行入口和网络行为。 混淆了仓库信任与扩展信任；Workspace Trust 不是进程或文件系统沙箱。 未知扩展先在隔离环境与空 Profile 评估，企业使用 AllowedExtensions、受控 Marketplace 和终端管理策略。 未批准扩展无法安装或被禁用，Developer: Policy Diagnostics 显示策略已应用。

架构选型与边界

VS Code 适合需要轻量编辑器核心、按语言和工具组合扩展、跨平台工作区一致的团队。它的优势也是治理成本来源：项目模型主要来自文件夹、配置和语言扩展，能力与风险随扩展组合变化。

需要强类型项目模型、深度 JVM 重构和统一集成工具链时，IntelliJ IDEA 往往减少自行组装成本；需要 Windows 原生 .sln、特定 C++ 或 .NET 工作负载时，应评估 Visual Studio。编辑器选型不能只比较启动速度，要比较项目模型准确性、调试深度、插件供应链、许可证、远程边界和团队维护成本。

Settings Sync 解决个人连续性，Profiles 解决个人场景隔离，仓库配置解决项目可复现，企业策略解决组织强制约束。四者不能互相替代。完整四层模型见设置治理专题。

权限、凭证与敏感信息

扩展、任务、调试配置、终端和工作区设置都可能触发代码执行。安装扩展前至少审查发布者身份、扩展 ID、版本、许可证、更新频率、依赖、遥测和网络目的地；Marketplace 的签名、恶意扩展下架与 block list 能降低风险，但不构成组织批准。微软分发的 VS Code 产品许可、MIT 许可的上游源码、Marketplace 服务和各扩展许可证也是不同对象，镜像和重分发前必须分别核对。

账号同步会把个人配置发送到所选账号对应的云服务。同步项可能暴露扩展清单、键位、代码片段和 UI 使用习惯；Profile 导出到 GitHub Gist 更会形成可分享链接。受监管环境必须先完成账号类型、数据驻留、离职回收和分享范围评审。

任务与调试配置中的环境变量只能引用占位名称，例如 ${env:APP_TOKEN}，不能提交值。调试控制台和终端日志也可能回显变量；团队应对输出、截图和诊断包设置脱敏规则。Developer: Policy Diagnostics 可能包含账号标识、会话和扩展访问账号的信息，分享前同样要审查。

团队治理

团队基线至少包含以下可验证合同：支持的 Stable 版本范围、升级观察窗口、允许的安装渠道、项目根判定、CLI 权威命令、工作区配置 owner、推荐扩展 owner、企业扩展准入、Settings Sync 账号规则和卸载离场流程。

.vscode/extensions.json 可以帮助成员发现扩展，但不能承担强制治理。企业扩展管理 说明，自 VS Code 1.96 起，extensions.allowed 支持按发布者、扩展、精确版本和平台限制安装；企业策略会覆盖用户和工作区设置。策略部署后使用 Developer: Policy Diagnostics 验证，不能只检查 MDM 控制台“已下发”。

升级采用小范围验证、扩大试用、全员发布、保留回退入口的节奏。固定烟雾测试至少覆盖 CLI、任务、断点、同步与策略诊断。发生故障时记录现象、版本、Profile、工作区信任、扩展差异和最小复现；不要把“清空配置后好了”当成根因。

最后保留一条硬边界：VS Code 是开发机上的代码执行平台，不是纯文本查看器。团队真正要治理的是“谁提供代码、谁提供扩展、谁能改变配置、哪些命令被执行、哪些数据会离开机器”。把这五个问题持续答清楚，编辑器效率才不会以供应链和凭证风险为代价。

团队自检

把检查放在干净账号或干净 Profile 上完成，避免用作者机器已有状态替项目补洞。任何一项无法用命令输出、策略诊断或仓库文件证明，都应回到对应配置层修复。

code --version 能对应到批准的通道、构建和安装渠道，旧 ZIP 与快捷方式没有抢占入口。干净检出从仓库根运行 CLI 成功，VS Code 任务调用同一条权威脚本。用户设置、Profile、工作区设置和企业策略各自有 owner，没有用账号同步分发团队强制规则。

tasks.json 与 launch.json 只使用项目相对路径和凭证占位符，反向打开错误目录时能产生可解释的失败证据。Restricted Mode 下先审查脚本与推荐扩展，信任范围没有扩大到下载目录、用户主目录或宽泛父目录。推荐扩展与允许扩展已经区分；发布者、版本、平台、许可和更新回滚路径均可追溯。

更新后固定烟雾测试覆盖 CLI、任务、断点、格式化差异、同步状态和策略诊断。离场流程能撤销同步账号、清理本机凭证与云端数据，并保留必要的故障证据。