VS Code Git集成需正确打开含.git的根目录、区分暂存与未跟踪文件、切换分支前处理未提交变更、首次推送需发布分支并配置上游。
VS Code 内置的 Git 集成足够日常使用，但默认配置下容易忽略状态同步、暂存逻辑和分支切换时的未提交变更处理——这些正是提交失败、丢失修改、切换分支被拒绝的常见原因。
Git 源代码管理视图打不开或不显示仓库状态
VS Code 的 Git 功能依赖工作区根目录下存在 .git 文件夹。如果打开的是子文件夹（比如只打开了 src/），即使父目录有仓库，Git 视图也不会激活。
- 确保用 VS Code 打开的是包含
.git的项目根目录（不是子目录） - 检查左下角状态栏是否显示分支名（如
main）；不显示说明未识别为 Git 仓库 - 终端中运行
git rev-parse --git-dir确认当前路径确实是 Git 工作树根 - 若手动初始化过仓库，但 VS Code 仍无响应，尝试点击源代码管理视图右上角的“…”，选
Refresh
点击“+”暂存文件后仍无法提交：未暂存 vs 未跟踪
VS Code 的“+”按钮只对已跟踪（tracked）且已修改的文件生效；新增文件默认处于“未跟踪（Untracked）”状态，需单独操作才能加入暂存区。
- 新文件会出现在源代码管理视图底部的
Untracked区域，右键它并选择Stage Changes，或点击其右侧的+ - 误点了
Discard Changes会直接丢弃未暂存的修改，不可撤销 - 想跳过暂存直接提交所有修改（含新文件），可在命令面板（
Ctrl+Shift+P）运行Git: Commit All，但不推荐用于生产环境——易漏审变更
切换分支时报错“Please commit your changes or stash them”
VS Code 默认禁止在存在未提交变更（包括已暂存和未暂存）时切换分支，这是 Git 的安全机制，不是插件 Bug。
- 先确认哪些文件有未提交变更：看源代码管理视图中
Changes和Untracked区域 - 若变更需要保留但暂不提交，用命令面板运行
Git: Stash，之后可自由切换分支；切回原分支后运行Git: Pop Stash - 若只是临时编辑、确认可丢弃，右键对应文件 →
Discard Changes（注意：该操作不经过回收站） - 勾选设置
git.confirmSync为false可关闭部分提示，但不会绕过 Git 本身的分支保护逻辑
推送（Push）失败：上游分支未设置或权限不足
首次推送新分支时，VS Code 默认不自动设置上游（upstream），导致 git push 无目标，报错类似 fatal: The current branch xxx has no upstream branch。
- 右键分支名 →
Publish Branch，这会执行git push -u origin xxx，建立本地与远程的追踪关系 - 若推送被拒绝（
rejected），大概率是远程已有更新：先Pull合并或变基，再重试 Push - GitHub/GitLab 等平台启用强制审查（Require PRs）或保护分支（protected branch）时，直接 Push 到
main会被拒，必须走 Pull Request 流程 - 确认凭证：Windows 用户常因 Windows Credential Manager 缓存旧 Token 导致 403，需在系统凭据管理器中删除对应 git 域名条目
分支名拼写错误、.gitignore 里漏掉构建产物、多人协作时忘记 Pull 就 Commit——这些不是 VS Code 的问题，但恰恰是在它流畅的 UI 下最容易被忽略的操作盲点。
