VSCode的Git集成需手动配置本地git命令、正确初始化仓库并识别Source Control面板三区域。未配置会导致文件不显示、暂存无效或推送失败，须检查PATH、.git目录及远程认证。
VSCode 的 Git 集成不是“开箱即用就全好使”的，它依赖本地 git 命令行工具、正确初始化的仓库，以及你对几个关键 UI 区域的识别。没配好会卡在“未跟踪文件”不显示、“暂存区”点不动、或提交后看不到远程同步状态。
确认 VSCode 能调用系统 git 命令
VSCode 的源代码管理（Source Control）视图所有操作都通过调用你本机安装的 git 可执行文件完成。如果它找不到，面板会直接提示“Git not found”或按钮全部灰掉。
- 打开 VSCode 终端（
Ctrl+`），输入git --version—— 必须返回类似git version 2.40.1的结果 - 如果报错
command not found，说明系统 PATH 没包含 git 安装路径；macOS 用户常见于用 Homebrew 安装但未运行brew install git后的 shell 初始化 - Windows 用户请确认安装 Git 时勾选了
Add Git to the system PATH，否则需手动把C:\Program Files\Git\cmd加入环境变量 - VSCode 启动前必须已配置好 PATH，重启 VSCode 才生效
初始化仓库或打开已有 .git 目录
VSCode 不会自动为你初始化 Git 仓库，也不会从子目录向上搜索 .git。它只认当前工作区根目录下存在 .git 文件夹的项目。
- 如果你刚建了个空文件夹，先在终端里进该目录，运行
git init，再用 VSCode 打开这个文件夹（不要打开父级目录） - 如果项目已用命令行
git clone下来，确保 VSCode 是打开clone出来的最外层文件夹，而不是里面某个子模块或 src 目录 - 打开后看左下角状态栏：应显示分支名如
main或master；若显示No source control providers registered，大概率是没找到.git
理解左侧 Source Control 面板的三个区域
这个面板不是装饰，每个区块对应 Git 的一个核心状态，误点或忽略某块会导致操作失效。
┌───────────────────────────────────┐ │ SOURCE CONTROL (Ctrl+Shift+G) │ ├───────────────────────────────────┤ │ CHANGES │ ← 未暂存的修改（working directory） │ → file1.js │ 点文件旁 + 号可暂存单个文件 │ → style.css │ 点顶部 ✓ 可暂存所有已追踪文件 │ │ │ STAGED CHANGES │ ← 已暂存（index），准备提交 │ → README.md │ 点文件旁 - 号可撤销暂存 │ │ │ ... │ └───────────────────────────────────┘
-
CHANGES区只显示「已被 Git 追踪过、且有改动」的文件；全新文件默认不出现，需先右键 →Stage Changes或点 + 号 - 想让全新文件一打开就出现在
CHANGES，需先在终端运行git add -N <file>（告知 Git “我要开始追踪它”），否则 VSCode 不认为它是“变更” - 提交前务必确认要提交的内容在
STAGED CHANGES区——这里才是git commit的实际输入源
提交、推送与处理认证失败
点击 STAGED CHANGES 上方的输入框写提交信息，按 Ctrl+Enter 提交。但提交成功 ≠ 推送到远程 —— VSCode 默认不做 git push，必须手动触发。
- 提交后左下角分支名旁会出现小箭头图标
↑1，表示本地比远程多 1 个 commit；点它即可推送 - 首次推送可能弹出认证窗口：GitHub/ GitLab 通常要求 Personal Access Token（PAT），而非账号密码；旧版密码方式已基本废弃
- 若推送失败并提示
Authentication failed，检查 VSCode 设置中git.terminalAuthentication是否为true（默认开启），否则凭据无法传给终端 - 远程 URL 错误也会导致推送失败：右键源代码管理面板空白处 →
Remote → Configure Remote可编辑origin地址
最容易被忽略的是：VSCode 的 Git 集成不会自动拉取远程新提交，也不会高亮当前分支落后多少。你得主动点左下角分支名 → Fetch，或设置 git.autofetch 为 true（但别开太频繁，尤其在慢网络下）。
