vscode 不自带 git，必须先安装 git 命令行工具并确保 git --version 可运行；装好后需重启 vscode，再检查设置中 git.path、状态栏分支显示及是否在仓库根目录；提交前务必先 pull 同步，避免推送失败。
VSCode 本身不自带 Git，必须先装 Git 命令行工具，否则所有“源代码管理”功能都灰掉、点不动——这是 90% 新手卡住的第一步。
Git 命令行没装好，VSCode 的 Git 就是摆设
VSCode 只是调用系统已安装的 git 可执行文件，它不内置 Git。哪怕你只打算点鼠标操作，也必须确保终端里能直接运行 git --version 并返回版本号（≥2.30 推荐）。
- Windows：安装时勾选 “Add Git to PATH” 或手动把 Git 安装目录下的
cmd子目录（如C:\Program Files\Git\cmd）加进系统环境变量 - macOS：用
brew install git最稳妥；若用官网包，注意检查是否启用了 “Install Command Line Tools” 选项 - Linux：
sudo apt install git（Debian/Ubuntu）或sudo dnf install git-all（Fedora），别只装git-core - 装完务必重启 VSCode——它只在启动时扫描一次
git路径，中途装好也不会自动识别
VSCode 检测不到 Git？先看底部状态栏和设置
如果左下角没有显示分支名（如 main），或点击“源代码管理”图标后提示 “Git not found”，不要急着重装，先排查这几个地方：
- 打开 VSCode 设置（
Ctrl+,），搜git.path，确认值是空的还是指向了错误路径；如果是后者，删掉它，让 VSCode 自动发现 - 按
Ctrl+Shift+P打开命令面板，输入Git: Show Git Output，点开看日志里有没有类似Failed to start git或spawn git ENOENT的报错 - 检查当前打开的文件夹是不是 Git 仓库根目录——VSCode 只对打开的**文件夹**做 Git 集成，单个文件或子目录不会激活源代码管理视图
- 某些安全软件（尤其 Windows 上的 McAfee、火绒）会拦截
git.exe启动，临时禁用试试
提交前不拉取，推送大概率失败
多人协作中，“直接改完就点 Commit & Push” 是最常见导致推送拒绝（rejected - non-fast-forward）的操作。VSCode 不会自动帮你同步远程最新提交。
- 每次准备提交前，先点底部状态栏右侧的云形图标（
Pull），或右键“源代码管理”视图里的“...”菜单选Pull - 如果拉取时提示有未提交修改，别硬点覆盖——这时该用
Stash：点“...” →Stash→ 填备注 → 再Pull→ 然后Pop Stash，冲突会在文件里标红 -
Commit & Push是两步合并操作，但底层仍是先commit再push；如果你只想暂存本地，就只点Commit（√ 按钮），别点下拉箭头 - 远程分支名要和本地一致，否则推送时得手动指定，比如
git push origin feature/login:feature/login—— VSCode 默认只推同名分支
分支切换卡住？检查工作树和未暂存修改
点击底部分支名切换时，如果弹窗卡住、无响应，或者切过去后文件内容没变，大概率是当前有未暂存或未提交的修改，Git 拒绝覆盖工作区。
- 先去“源代码管理”视图看有没有带
M（modified）、U（untracked）标记的文件；有就决定是Stage提交，还是Discard放弃 - 如果正在用
git worktree，VSCode 当前窗口可能绑定在某个工作树路径下，而你试图切换的是主工作树的分支——这时得关掉当前窗口，用 VSCode 重新打开另一个工作树目录 - 某些大文件（如
node_modules、dist）没加进.gitignore，会导致状态扫描极慢，表现为分支列表半天不出来；加完忽略后，执行git rm -r --cached node_modules清缓存
Git 在 VSCode 里看着点几下就能跑通，但每个按钮背后都是原生命令在执行；真正卡住的时候，往往不是界面问题，而是本地仓库状态和远程历史没对齐——这时候打开集成终端敲两行 git status 和 git log --oneline -n 5，比反复点鼠标快得多。
