Git 必须系统安装并配置正确：终端执行 git --version 验证安装；全局设置 user.name 和 user.email 且邮箱需与 GitLab 账户一致；SSH 密钥须用 ssh-keygen -t ed25519 -C "邮箱" 生成于默认路径；remote URL 必须手动改为 SSH 格式（git@host:group/repo.git）并验证推送。
确认 Git 是否已就绪，而不是只靠 VS Code 自带支持
VS Code 内置 Git 支持，但仅限调用系统已安装的 git 命令。如果终端里执行 git --version 报错或无输出，说明 Git 没装好，VS Code 的 Git 功能会直接失效（比如源代码管理面板灰掉、无法提交）。
实操建议：
- Windows 用户：安装 Git for Windows 时，在 “Adjusting your PATH environment” 步骤选 “Git from the command line and also from 3rd-party software”，确保 VS Code 终端能识别
git - macOS 用户：用
brew install git安装；若已存在旧版，先运行which git看路径，避免 Homebrew 版和 Xcode 自带版冲突 - Linux 用户：用系统包管理器安装（如
sudo apt install git），别依赖 VS Code 自带的简化版
全局 user.name 和 user.email 必须设，且要匹配企业平台账号
没配这两项，git commit 仍能执行，但提交记录里作者显示为 “Unknown”，企业 GitLab/GitEE 后台可能拒绝推送，或导致代码归属无法审计。
实操建议：
- 在 VS Code 终端中运行：
git config --global user.name "张三"和git config --global user.email "zhangsan@company.com.cn"—— 邮箱必须和你在 GitLab 账户绑定的完全一致 - 验证是否生效：
git config --global --list，检查输出中是否有对应字段 - 不要用中文引号、空格或全角符号；name 可含空格，但 email 必须是标准格式（如不含中文、特殊符号）
生成 SSH 密钥时别跳过 -C 参数，且路径必须用默认值
很多用户用 ssh-keygen -t ed25519 直接回车，结果密钥生成在非标准路径（比如桌面），后续 VS Code 或 ssh-add 找不到，ssh -T git@gitlab.company.com 就一直报 Permission denied (publickey)。
实操建议：
- 务必加上
-C参数并填企业邮箱：ssh-keygen -t ed25519 -C "zhangsan@company.com.cn" - 提示
Enter file in which to save the key时，直接回车——使用默认路径（~/.ssh/id_ed25519），别手动输路径 - 提示
Enter passphrase时也直接回车（企业环境通常不设密码，否则每次 push 都要输） - 生成后立刻验证：
ls -l ~/.ssh/id_ed25519*，应看到私钥（600 权限）和公钥（644 权限）两个文件
VS Code 不自动处理 remote URL 协议切换，HTTPS 和 SSH 必须手动转换
这是最常被忽略的环节：即使你 SSH 密钥已上传到 GitLab、ssh -T 测试成功，VS Code 里仍可能走 HTTPS 协议，导致推送时弹窗要输密码，或直接报 401 Unauthorized。
实操建议：
- 进项目根目录终端，运行
git remote get-url origin—— 如果输出是https://gitlab.company.com/group/project.git，说明还在走 HTTPS - 立刻切换为 SSH：
git remote set-url origin git@gitlab.company.com:group/project.git（注意不是ssh://开头，也不是带/的路径） - Windows 用户注意：SSH URL 中的主机名必须和
ssh -T测试时用的一致（比如git@gitlab.company.com，而非git@internal-git.company.com） - 改完后，在 VS Code 源代码管理面板点「同步更改」，观察底部状态栏是否显示
origin而非报错；再试一次git push，不应再弹密码框
真正卡住人的地方，往往不是密钥生成本身，而是 remote URL 没换、邮箱没对齐、或者权限没收紧（尤其是 Linux/macOS 下 ~/.ssh 目录权限不是 700 会导致 ssh-agent 拒绝加载）。每一步都建议用终端命令验证，别只盯着 VS Code 图形界面看。
