VS Code 的 Git 功能依赖系统级 Git CLI 工具，非插件自带；配置失败主因是 Git 未安装、PATH 未正确配置、git.path 路径填写错误或缺失 user.name/user.email 基础配置。
git 不是 VS Code 插件，而是必须独立安装、再由 VS Code 调用的系统命令行工具。配置失败的绝大多数情况，不是“没点对设置”，而是 git 本身没装好、路径没认准、或关键配置漏了。
确认 git 是否真能被 VS Code 调用
打开 VS Code 内置终端（Ctrl + `），直接运行：
git --version
如果报 command not found 或无输出，说明 VS Code 根本找不到 git —— 此时所有 Git 功能（源代码管理面板、状态栏分支名、推送按钮）都会灰掉或失效。
- Windows 用户：检查是否安装了
Git for Windows，且安装时在 “Adjusting your PATH environment” 步骤选了 “Git from the command line and also from 3rd-party software” - macOS 用户：用
which git看路径，若输出/usr/bin/git（Xcode 自带旧版），建议用brew install git替换，并把新路径（如/opt/homebrew/bin/git）填进 VS Code 设置 - Linux 用户：确保用
sudo apt install git（Ubuntu/Debian）或对应包管理器安装，别依赖桌面环境自带的阉割版
git.path 必须手动设，尤其 macOS/Linux GUI 启动场景
即使终端里 git --version 正常，VS Code 图形界面启动时可能拿不到 shell 的 PATH，导致 SCM 面板不显示分支、右下角空白。最稳解法是硬编码路径：
- 按
Ctrl + ,打开设置 → 搜索git.path→ 点 “Edit in settings.json” - 填入绝对路径，注意格式：
- Windows：
"git.path": "C:/Program Files/Git/bin/git.exe"（用正斜杠，别用反斜杠） - macOS：
"git.path": "/opt/homebrew/bin/git"（Homebrew 安装路径） - Linux：
"git.path": "/usr/bin/git"（确认是新版，非/usr/libexec/git-core/git）
- Windows：
- 保存后必须完全退出 VS Code（关所有窗口），再重开，热重载不生效
user.name 和 user.email 不配，提交记录就是“Unknown”
没设这两项，git commit 仍能跑通，但企业平台（GitLab/Gitee）可能拒绝推送，或导致代码归属审计失败。
- 在 VS Code 终端执行（邮箱必须和账号完全一致）：
git config --global user.name "张三"<br>git config --global user.email "zhangsan@company.com.cn"
git config --global --list，检查输出里有对应行user.email 必须是标准邮箱格式（不含中文、特殊符号）SSH 密钥没走默认路径，git push 就卡在 Permission denied (publickey)
VS Code 推送依赖系统 SSH 代理，而代理只认默认路径下的密钥。很多人用 ssh-keygen -t ed25519 回车生成，结果密钥落在桌面或文档目录，ssh-add 和 VS Code 都找不到。
- 正确做法：用完整命令生成到默认路径（
~/.ssh/id_ed25519）：
ssh-keygen -t ed25519 -C "zhangsan@company.com.cn"
ssh-add ~/.ssh/id_ed25519
git@host:group/repo.git，不是 https:// 开头ssh -T git@host（如 ssh -T git@gitlab.company.com），看到 welcome 信息才算通git 可执行文件”，所有步骤都围绕这个核心。最容易被跳过的其实是 git.path 手动指定和 SSH 密钥的默认路径约束——这两个点一错，整个工作流就卡在第一步。 
