VSCode SCM装饰器自动显示，无需手动开启；关键取决于.git位置、Git路径配置和文件监听是否正常。首要排查：工作区根目录下是否存在可读的.git、git.path是否正确、fs.watch是否生效。
VSCode 的 SCM 装饰器（即文件名旁的 Git 状态标记：绿色/蓝色/灰色小圆点、修改图标等）不是独立开关项，它由 Git 集成状态、文件系统监听机制和工作区结构共同决定——只要 Git 正常工作且项目根目录下有 .git，装饰器就会自动出现；反之，它不会“手动开启”，只能排查阻断点。
SCM 装饰器不显示的首要排查点：.git 位置与工作区根目录
VSCode 只认你「打开的文件夹」为工作区根，并只向上扫描一级查找 .git。常见错误是：
- 把项目放在子目录里（如
/project/src），却打开的是/project——而.git实际在/project/src/.git - 用 VSCode 打开单个文件（而非文件夹），此时无工作区根，
.git完全不可见 - 项目根目录下是
.git/子目录，但权限被限制（如 Docker 挂载时 uid/gid 不匹配），VSCode 读不到
验证方式：在资源管理器顶部看路径是否包含 .git 文件夹；终端中执行 git status 能否正常返回；若能，但 VSCode 仍无装饰，则继续往下查。
Git 可执行文件未被识别导致 SCM 视图和装饰器双双失效
SCM 装饰器依赖底层 Git CLI 调用解析 diff 和状态。如果 VSCode 找不到 git 命令，不仅 SCM 视图空白，连行间装饰（如修改标记）也不会渲染。
- macOS 上 Homebrew 安装的 Git 默认路径是
/opt/homebrew/bin/git（Apple Silicon）或/usr/local/bin/git（Intel），但 VSCode 终端环境 PATH 可能不包含它 - Windows 上 Git 安装路径含空格（如
C:Program FilesGitingit.exe）时，VSCode 有时会因未加引号而解析失败 - 检查方法：命令面板（
Cmd+Shift+P）输入Git: Show Git Output，看是否有 “failed to spawn git” 类错误
修复方式：在 settings.json 中显式指定路径，例如：
"git.path": "/opt/homebrew/bin/git"
改完必须重启 VSCode，仅重载窗口无效。
文件系统事件监听失败导致装饰器不更新
VSCode 默认靠 fs.watch() 监听文件变更来触发装饰器刷新。但在某些场景下它会静默失效：
- NFS 或 WSL2 跨文件系统挂载目录
- Docker Desktop 的 volume 挂载（尤其 macOS 上的
/Users映射） - Windows 上启用了实时防病毒扫描（如 Windows Defender）
现象是：手动 git add 后 SCM 视图立刻更新，但你在编辑器里改完保存，左侧文件树和行号旁毫无反应。
验证方式：打开开发者工具（Cmd+Shift+I → Console），执行 require('fs').watch。若返回 undefined，说明 Node.js 层已禁用原生监听。
强制启用轮询（代价是 CPU 占用略高）：
"files.usePolling": true
注意：这个设置对大仓库影响明显，建议仅在确认监听失效后启用，且优先考虑调整挂载方式（如 WSL2 改用 \wsl$ 访问）。
装饰器颜色/样式异常或部分缺失
这不是功能故障，而是主题或扩展干扰的结果：
- 某些高对比度主题会覆盖装饰器图标颜色（比如把绿色改成白色，导致看不见）
- GitLens 等扩展默认接管所有 Git 状态展示，可能隐藏原生装饰器（检查 GitLens 设置里的
gitlens.codeLens.scopes或gitlens.gutter.enabled） - 自定义 CSS 扩展（如 Custom CSS and JS Loader）若注入了
.monaco-editor .margin-view-overlays .dirty类规则，可能误删图标
临时诊断法：启动 VSCode 干净模式（code --disable-extensions），再打开项目。若此时装饰器恢复，问题就出在某个扩展上。
真正卡住的人，往往困在「以为要开某个开关」，其实关键就三件事：确认 .git 在工作区根、确保 git.path 可达、验证 fs.watch 是否活着。其它都是干扰项。
