VSCode 的 Git 功能失效主因是未正确配置系统级 Git 或未打开 Git 仓库根目录。需确保终端可运行 git --version、VSCode 能继承 PATH、git.path 设置正确，并通过 Open Folder 打开含 .git 的目录。
VSCode 本身不带 Git，必须先装好系统级 Git 并让 VSCode 找得到它——这是 90% 的“Git 不显示”“按钮灰显”“右下角没分支名”问题的根源。
确认系统 Git 已安装且可被调用
VSCode 启动时会尝试从 PATH 查找 git 命令。不是“装了就行”，而是终端里能运行，VSCode 也得能运行。
- 打开系统终端（非 VSCode 内置 Terminal），执行
git --version；若报错或无输出，说明 Git 没装好或没进PATH - Windows 用户常见问题是：Git for Windows 安装时没勾选 Add Git to the system PATH；重装时务必选上
- macOS 用户常见问题是：Terminal 能用
git，但 VSCode GUI 启动时没继承 shell 的PATH；需在~/.zshrc（或对应 shell 配置）中确保export PATH="/opt/homebrew/bin:$PATH"类路径生效，并完全重启 VSCode（不只是 Reload Window）
手动指定 git.path（当自动发现失败时）
如果 VSCode 仍找不到 Git，别反复重装，直接配路径更可靠。
- 按
Ctrl+Shift+P（Win/Linux）或Cmd+Shift+P（macOS），输入Preferences: Open Settings (JSON) - 添加或修改这一行：
"git.path": "/usr/local/bin/git"
（macOS/Linux）或"git.path": "C:\Program Files\Git\bin\git.exe"
（Windows） - 路径必须指向
git可执行文件本身，不是目录；可用which git（macOS/Linux）或where git（Windows）查准位置 - 改完保存，VSCode 会自动重启 Git 服务；再按
Ctrl+Shift+P输入Git: Show Git Output，看输出面板是否出现Using git X.X.X from ...
验证工作区是否处于 Git 仓库根目录
VSCode 的 Git 功能只在“打开的文件夹是 Git 仓库根目录”时激活。开错路径，整个 SCM 面板就失效。
- 检查项目根目录下是否有
.git文件夹；没有就先执行git init或git clone - 如果已初始化但 VSCode 仍不识别，大概率是你用“文件 → 打开”打开了某个子文件（如
src/index.js），而不是“文件 → 打开文件夹”选中含.git的父目录 - 关闭当前窗口，用
File → Open Folder...重新选择正确路径；左下角应立刻出现分支名（如main），SCM 面板显示 “CHANGES” 区域 - 若仍显示
No source control providers are registered，说明 VSCode 根本没识别到 Git 上下文，优先回退检查前两步
启用 Git 扩展并检查基础设置
VSCode 默认启用 Git 支持，但个别情况可能被关掉或冲突。
- 按
Ctrl+,打开设置，搜索git.enabled，确认值为true - 搜索
git.autoRepositoryDetection，建议保持默认true（自动扫描子文件夹找 .git）；若项目结构特殊（如 mono-repo），可设为false并手动管理 - 不推荐安装第三方 Git 插件覆盖原生功能；VSCode 自带 Git 集成足够稳定，插件反而容易引发状态不同步
- 首次提交前，VSCode 可能弹窗让你配置
user.name和user.email；也可提前在终端运行git config --global user.name "Your Name"和git config --global user.email "you@example.com"
最常被忽略的是：VSCode 不会替你决定“哪个文件夹是仓库”。它只响应你打开的路径，而 Git 的一切行为都绑定在那个 .git 目录上。路径错一点，后面所有操作都在真空里发生。
