Git常见报错排查与解决：从环境配置到远程仓库

你肯定遇过这样的情况：项目马上要上线，git push 却提示 authentication failed；新同事入职，第一条命令就卡在“git 不是内部或外部命令”；合并分支时又遇到 fatal: refusing to merge unrelated histories，网上搜索半天，给了七八个命令，越改越乱。我这些年做技术支持和团队协作，Git 报错见过不少，大部分问题翻来覆去就那么几个根源。这篇整理了我这几年收集的常见报错、踩坑过程和最终解决思路，覆盖环境安装、远程仓库、本地分支、提交钩子、免密配置几大类，遇到问题可以直接对号入座，也可以收藏起来当速查手册用。

1. 装不上、装完不认账：环境层的报错最磨人

环境类报错听起来低级，但卡住老手的案例也不少。原因很简单：环境变量、系统组件这些东西，平时根本不会去动，一旦出问题，第一反应往往是“重装”。可重装好几次，问题依然在，最后才发现是 PATH 或者系统功能缺失。

1.1 “git 不是内部或外部命令”的完整排查链路

这个报错在 Windows 上出现频率最高，本质就一句话：系统在 PATH 环境变量里找不到 git.exe。但“找不到”可以分为好几种情况，排查顺序很重要。

第一步，先确认 Git 到底装没装上。很多人说“我装了”，但装的其实是 TortoiseGit 的客户端，纯小乌龟不带命令行，或者只勾选了“Git Bash”组件，没把 Git 加入命令行。安装 Git for Windows 时，有一页叫“Adjusting your PATH environment”，建议选择中间那个单选按钮：

code复制Git from the command line and also from 3rd-party software

这一项会把 Git 加到系统 PATH，CMD、PowerShell、VSCode 都能直接调用 git。如果选了第一个“Only use Git from Git Bash”，CMD 里自然认不出 git。

第二步，安装完成后没有重新打开终端。这个细节特别容易被忽略，PATH 是终端启动时读取的，装完 Git 后，旧的 CMD 窗口仍然保留着旧环境变量。关掉所有终端窗口，重新开一个，再执行：

bash复制git --version

如果还是报错，第三步就只能手动查 PATH 了。在 CMD 里执行：

bash复制where git

什么输出都没有，就去安装目录确认 git.exe 是否存在。默认路径一般是：

code复制C:\Program Files\Git\cmd\git.exe

然后打开“系统属性 → 环境变量”，找到系统变量里的 Path，确认有没有把 C:\Program Files\Git\cmd 加进去。没有就手动添加，添加完记得点“确定”，再重开终端测试。

注意：环境变量分“用户变量”和“系统变量”。如果你把 Git 装到了用户目录下面，只需要改用户变量；如果装在 Program Files，就要看系统变量。两边都加上也没问题，以系统变量为优先。

这里还有一个隐藏坑：如果之前装过其他版本的 Git，或者手动改过 PATH，可能会同时存在多个 Git 路径。where git 输出多个路径时，极容易旧版本覆盖新版本，导致命令行为不一致。建议把不需要的路径清掉，只保留一个 Git 安装目录。

1.2 Git Bash 能打开但马上闪退

这个报错不弹出来，很多人反而更懵。Git Bash 窗口闪一下就没，无法输入任何命令。

我遇到过最典型的场景：系统临时目录 TMP、TEMP 环境变量被指向了一个不存在的路径，或者被某些清理软件给删了。Git Bash 启动时依赖临时目录写缓存，目录无效就直接退。

排查方式：

bash复制echo $TMP
echo $TEMP

如果输出为空或者路径不存在，去系统环境变量里把这两个变量修正：

code复制C:\Users\你的用户名\AppData\Local\Temp

确认这个目录真实存在且可写。还有一个可能性是终端集成冲突，比如 Windows Terminal 配置了错误命令行参数。可以先从开始菜单直接启动 Git Bash，如果开始菜单能正常打开，问题就出在第三方终端的启动参数上，可以在 Windows Terminal 的配置文件里把 Git Bash 的启动路径改为：

bash复制C:\Program Files\Git\bin\bash.exe --cd-to-home

--cd-to-home 这个参数很重要，默认 Git Bash 会尝试进入 %USERPROFILE%，如果当前用户目录权限异常也会闪退。

1.3 安装过程报 0x800f0950，查 Windows 组件

这个错我见过两次，都是在 Windows 10 上安装 Git 或某些开发工具时出现的。0x800f0950 本身不是 Git 的报错，而是 Windows 功能启用失败错误，常见于系统缺少 .NET Framework 3.5 相关组件，或系统更新文件损坏。

出现这个错误时，先别急着换 Git 版本。打开“控制面板 → 程序 → 启用或关闭 Windows 功能”，勾选“.NET Framework 3.5（包括 .NET 2.0 和 3.0）”，点确定让系统联网安装。如果安装失败，再用管理员权限打开 CMD，执行：

bash复制dism /online /enable-feature /featurename:NetFX3 /All /LimitAccess /Source:C:\Windows\WinSxS

/Source 也可以指向系统镜像里的 sources\sxs 目录。执行完重启电脑，再重新安装 Git。

这里要提醒一句：0x800f0950 经常混在“安装软件失败”的场景里，但不代表每个软件安装失败都是这个原因。建议先看安装日志，确认失败发生在哪个阶段。如果 Git 安装包本身下载不完整，也可能会报各种奇怪的错误码，重新下载官方安装包再试往往更省时间。

1.4 wmic.exe 弹窗与 Git 的关系

wmic.exe 弹窗这个问题，最近出现频率明显变高了。它不是 Git 本身产生的，但很多开发工具会调用 wmic 检测系统信息，比如检查 CPU 或系统版本，而 Windows 11 已经默认弃用 wmic，弹窗就会一次一次出现。

如果弹窗恰好在你打开 Git Bash 或执行某些 Git 命令时出现，说明某个脚本或服务正在调用 wmic。排查步骤可以这样走：

1. 打开任务计划程序库，看有没有可疑任务。
2. 检查系统服务里有没有第三方软件的“自动更新”或“系统检测”服务。
3. 在 CMD 里执行 where wmic 看它被哪个路径接管。

临时压缩弹窗频率，可以重命名 C:\Windows\System32\wbem\wmic.exe，但我不建议这么做，因为某些老软件真的依赖它，贸然改名可能导致其他程序报错。更稳妥的办法是找到调用方，把脚本里的 wmic 换成 PowerShell 的 Get-CimInstance。比如原来命令是：

bash复制wmic cpu get name

PowerShell 对应写法：

powershell复制Get-CimInstance Win32_Processor | Select-Object -ExpandProperty Name

如果你只是想让 Git Bash 的提示不触发 wmic，基本不用处理它。这个弹窗和 Git 属于“同屋不同房”的关系，别被带偏。

2. 远程仓库交互：克隆失败、认证不过、SSL 证书这些老大难

远程仓库的报错信息通常最长，也最容易把人吓住。一长串 URL、SSL、OpenSSL 混在一起，新手看到就想去网上复制一段“万能命令”。其实远程仓库的报错可以分三类：连不上、不信任、不认账。只要先分清楚是哪一类，解法就清晰了。

2.1 fatal: unable to access ... Failed to connect to port 443

这个报错的完整信息通常长这样：

text复制fatal: unable to access 'https://github.com/xxx/yyy.git/': Failed to connect to github.com port 443 after 21011 ms: Couldn't connect to server

表面看是网络不通，但实际上，最大的嫌疑是代理配置。很多开发者装过代理工具或公司网络要求配置代理，Git 会把代理设置记到全局配置里，换了个网络环境后，这个代理配置就成了累赘。

排查顺序：

bash复制git config --global --list

看输出里有没有 http.proxy 或 https.proxy。如果有一行类似：

ini复制http.proxy=http://127.0.0.1:7890
https.proxy=http://127.0.0.1:7890

而当前网络已经不需要这个代理，直接清掉：

bash复制git config --global --unset-all http.proxy
git config --global --unset-all https.proxy

清完再重新执行 git clone 或者 git fetch，大概率就通了。另一种情况是在公司内网，Git 需要走公司代理才能访问外网，这时要反过来设置：

bash复制git config --global http.proxy http://代理服务器地址:端口

设置完再测试。如果还是连不上，就要检查本地防火墙或者安全软件是否拦截了 Git 进程。Windows 上常见的是某些安全软件把 git.exe 或者 ssh.exe 的网络请求拦掉，弹窗没注意，网络就全断了。

2.2 OpenSSL SSL_read: Connection was reset 和 SSL certificate problem

这类报错在 HTTPS 协议下特别常见，我摘两个典型：

text复制error: OpenSSL SSL_read: Connection was reset by peer, errno 10054
error: SSL certificate problem: unable to get local issuer certificate

先说 errno 10054，它表示连接被对端重置。原因可能包括：网络不稳定、代理中断、防病毒软件扫描 HTTPS 流量、Git 版本过旧。我曾经遇到过一个案例，同事每隔几次 push 就报 10054，最后发现是他公司无线网络丢包太严重，换成有线网络后再没出过。所以第一步不是改配置，而是换个网络环境测试，验证是不是 Git 本身的问题。

如果网络正常、换网络也复现，那就要考虑 Git 版本。老版本 Git for Windows 的 OpenSSL 和 TLS 兼容性确实差一些，去官网下载最新版，装完再试。

SSL certificate problem: unable to get local issuer certificate 则是证书链验证失败。常见根源是本地系统根证书库不全（某些精简系统把证书精简了），或者公司用了自签 CA。网上给的最多解法是：

bash复制git config --global http.sslVerify false

我不建议一上来就干这事，因为它是全局关闭 SSL 证书校验，等于告诉 Git“不管对方证书是真是假都可以建立连接”，在公网环境下有中间人攻击风险。更合理的做法是，如果是公司内网自签证书，把公司根证书导出成 .crt 文件，然后配置：

bash复制git config --global http.sslCAInfo "D:\certs\company-root.crt"

这样 Git 只信任你指定的根证书，而不是完全不过问。临时排查问题需要绕过时，也建议在项目仓库目录下临时设置，而不是全局：

bash复制git config http.sslVerify false

问题定位完，马上改回来。

2.3 Git clone 时 fatal: repository not found

仓库地址明明存在，clone 却报 repository not found，遇到这种情况别急，先分清你用的是 HTTPS 还是 SSH。

HTTPS 地址下，最常见的是凭据过期。GitHub 早就取消了账号密码方式，如果你在用密码 git clone，一定会报这个错。需要生成 Personal Access Token（PAT），然后在 clone 时把 token 当密码输入，或者直接拼到 URL 里：

bash复制git clone https://<token>@github.com/username/repo.git

SSH 地址下，repository not found 往往是公钥没配对。检查一下当前用的 SSH 地址：

bash复制git remote -v

如果是：

text复制git@github.com:username/repo.git

而你的公钥没有添加到那个账号下，就会报 not found。用 ssh -T git@github.com 可以快速验证认证是否通过。如果输出里显示你的用户名，说明 SSH 认证没问题，再检查仓库地址有没有拼错，私有仓库是否有访问权限。

2.4 Login failed. Check API token or GitLab version

这条报错在 GitLab 环境里很典型，尤其是团队从旧版 GitLab 升级之后。完整提示类似：

text复制Login failed. Check API token or GitLab version. Log in via Git if the version of GitLab is lower than 7.10.

字面意思是：登录失败，请检查 API token 或 GitLab 版本。出现这个报错，往往是 GitLab 新版不再支持用户名密码认证，要求使用 Personal Access Token。也有可能是 Git 版本太老，对 GitLab API 的支持不完整。

解决办法：登录 GitLab，在用户设置里生成一个 Personal Access Token，勾选 write_repository 权限，然后把远程地址改掉：

bash复制git remote set-url origin https://oauth2:<token>@gitlab.example.com/group/repo.git

或者用 SSH 方式彻底避开 token：

bash复制git remote set-url origin git@gitlab.example.com:group/repo.git

我之前处理过一次类似问题，同事的 GitLab 版本只有 9.0，而本地 Git 还是 1.8 时代的老古董，git push 一直报这个错。升级 Git 到新版后，问题直接消失。所以遇到这条报错，建议先检查两边版本，再确认 token，最后再动 URL。

2.5 认证失败后凭据缓存没有清干净

fatal: Authentication failed for 'https://...' 这个报错很隐蔽。有时候你换了新 token，却还是失败，不是 token 错了，而是 Git 凭据管理器里缓存了旧的密码。Git for Windows 默认使用 Git Credential Manager，它会记住你上一次输入的凭据。

排查方式，在 CMD 里执行：

bash复制cmdkey /list | findstr /i git

如果列出了旧凭据，删掉：

bash复制cmdkey /delete:git:https://github.com

然后重新执行 git push，让它弹出新的凭据输入框。也可以用命令直接清空：

bash复制git credential-manager erase

输入 protocol=https 后按两次回车，就能把当前仓库的凭据清掉。这个小操作我写过好几个人的电脑，他们之前都是改各种配置都不生效，结果只是旧凭据在捣乱。

3. 分支、提交、合并：本地操作最容易翻车的高频报错

如果说环境问题和远程问题只是偶尔遇到，那本地操作里的这几类报错，几乎每个 Git 用户都躲不过。它们的共同点在于：报错信息看着吓人，但只要理解了背后那几个基本概念——工作区、暂存区、HEAD、提交历史——就能迅速判断到底该怎么处理。

3.1 fatal: refusing to merge unrelated histories

这条报错太经典了，我几乎每周都能在社区里刷到一次。完整信息：

text复制fatal: refusing to merge unrelated histories

触发场景通常是这样的：远程仓库在初始化时已经生成了 README 文件，你本地又执行了 git init 并提交了代码，然后把远程加为 origin，执行 git pull，Git 发现两边的提交历史毫无交集，于是拒绝合并。

为什么会拒绝？因为 Git 的合并机制是基于共同祖先提交的。两个提交历史完全不相干的仓库，没有共同祖先，Git 不知道该以谁为基准合并，干脆报错。

解决办法很简单，在 pull 或 merge 时加上：

bash复制git pull origin master --allow-unrelated-histories

执行完 Git 会把两边历史强行接起来，合并成一个提交。如果出现冲突，就按普通冲突处理，解决后 git add 再 git commit。

但我要提醒一句：--allow-unrelated-histories 是“强行续命”的命令，它能解决眼前的问题，却可能让你的提交历史变得非常奇怪。比如本地有个旧项目，远程是一个全新的空仓库，直接这么合，没问题；但如果两边其实是同一个项目的不同版本，最好还是先确认谁的代码是最新的，再决定是否合并。

预防办法最干脆：新项目如果远程仓库已经初始化了，不要用 git init，直接 git clone。如果本地已经有代码，先把远程仓库的文件拉下来，再把本地代码复制进去，用 git status 观察差异。

3.2 LF will be replaced by CRLF：行尾符不是小事

这个警告出现频率极高，尤其是 Windows 用户把 core.autocrlf 设置为 true 时：

text复制warning: LF will be replaced by CRLF in package.json.

原因再简单不过：Windows 换行符是 CRLF（回车+换行），Linux/macOS 是 LF（换行）。Git 默认在提交时把工作区文件的 CRLF 转换成 LF 存到仓库，在检出时又把 LF 转换成 CRLF，于是每次操作都会出现这个提示。

这个警告通常不影响功能，但团队协作时如果处理不好，会出现“整个文件都显示被修改”的恐怖现场。处理方式有三种：

我的建议是，团队协作不要靠每个人自己设置 core.autocrlf，而是用 .gitattributes 文件固定规则，放在仓库根目录。比如：

gitattributes复制* text=auto
*.js text eol=lf
*.ts text eol=lf
*.md text eol=lf
*.bat text eol=crlf

这样无论谁在什么平台拉代码，Git 都会按文件类型强制使用指定换行符，彻底消灭“打开文件全是红绿线”的悲剧。

3.3 detached HEAD：游离态 HEAD 下丢了改动

第一次看到 HEAD detached at 1a2b3c4d 这句话的人，多半会心头一紧。其实它没有破坏任何东西，只是说明你当前的 HEAD 没有指向任何分支，而是直接指向了一个具体的提交。

触发方式很简单：

bash复制git checkout 1a2b3c4d

或者直接点击 IDE 里的某个历史提交。这时你查看 git status，会看到：

text复制HEAD detached at 1a2b3c4d
nothing to commit, working tree clean

此时你确实处于一个可读的“历史快照”里。如果只是看看代码，不打算改，直接用 git checkout 原分支名 切回去就行。但如果在这个状态下做了修改，然后直接切走，改动就可能丢掉。正确做法是创建一个分支，把改动留在分支上：

bash复制git switch -c fix-xxx

这样当前游离的提交和历史改动就被分支引用住了，不会再被“遗忘”。

在 Git 2.23 之后，官方推荐用 git switch 而不是 git checkout 切换分支，因为它语义更清晰，不容易误操作。

3.4 Your branch and 'origin/master' have diverged 怎么处理

如果你在本地提交了一个 commit，而远程也有别人推了新提交，两边就分叉了。这时 git status 会显示：

text复制Your branch and 'origin/master' have diverged,
and have 1 and 1 different commits each.

这条信息的意思是：本地有一个远程没有的提交，远程也有一个本地没有的提交。接下来直接 git push 会被拒，必须先合并或变基。

处理方式有两种，取决于团队习惯：

bash复制git pull --rebase

和：

bash复制git pull --no-rebase

--rebase 会把本地的提交“挪”到远程最新提交之后，提交历史是一条直线，干净但会改写本地提交时间点；--no-rebase 会生成一个 merge 提交，历史出现分支结构，但更忠实于实际发生的过程。

如果你的 Git 版本是 2.27 以上，直接执行 git pull 还可能出现：

text复制fatal: Need to specify how to reconcile divergent branches.

这是因为新版 Git 不再默认替你决定 rebase 还是 merge。解决办法是配置一个默认策略：

bash复制git config --global pull.rebase false

如果你喜欢 rebase，就把 false 改成 true。这不是什么高深技巧，但能省掉每次手动 --rebase 的麻烦。

4. 提交规范与钩子：被 pre-commit 拦下来的报错别硬推

这类报错不来自 Git 本身，而是来自 husky、lint-staged、commitlint 这些工具。它们挂在 Git 钩子上，在 commit 之前执行检查，一旦检查失败，Git 会拒绝提交并输出一大段报错。很多人以为是 Git 坏了，其实是代码质量问题被钩子拦住了。

4.1 pre-commit hook failed 的完整处理流程

当执行 git commit 时，看到类似输出：

text复制husky > pre-commit (node v18.16.0)
  ↓ Stashing changes... [skipped]
  → Running tasks...
  ✖ lint-staged failed - please check your git config and try again

核心信息是 lint-staged 执行失败。它通常是用来跑 ESLint、Prettier 或单元测试的。此时不要急着加 --no-verify，先往上报错，找到具体是哪一条规则失败。

比如 ESLint 报的是“存在未使用的变量”，那直接打开对应文件修复。如果一堆文件都有这个问题，可以用 lint-staged 的自动修复机制：

bash复制npx eslint --fix src/xxx.js

修完再 git add 然后重新 commit。

还有一种情况是钩子本身坏了，比如 Windows 上出现：

text复制env: 'sh\r': No such file or directory

这是 husky 脚本中的换行符被转成了 CRLF，导致 sh 无法识别。解决方式是在项目根目录执行：

bash复制git config core.autocrlf false

然后把 .husky 目录里的文件重新保存为 LF 格式。更简单的方法是重装钩子：

bash复制npx husky install
npx husky add .husky/pre-commit "npm test"

如果你确实需要临时跳过钩子，可以：

bash复制git commit --no-verify -m "临时提交"

但这条命令会让代码绕过所有检查，紧急修复时可以，日常不建议。我在团队里见过几次，有人用 --no-verify 把带 ESLint 报错的代码合进主干，结果整个部门的 CI 红了大半天。

4.2 commit-msg 钩子报错：提交信息格式不对

如果你用 commitlint 做提交规范检查，那 git commit 时经常会看到：

text复制⧗   input: 修复了一个bug
✖   subject may not be empty [subject-empty]
✖   type may not be empty [type-empty]

意思是提交信息不符合 Angular 提交规范，必须包含类型和作用域。规范的提交信息长这样：

text复制feat(user): 增加登录验证码
fix(order): 修复订单金额计算错误
docs(readme): 补充部署说明

提交示例：

bash复制git commit -m "feat(login): 增加图形验证码校验"

这种规范看着麻烦，但配合 git log --oneline 看历史时，整个仓库的脉络会特别清楚。团队协作时，强烈建议在本地配置 commitlint，早报错早改，总比 push 之后被 CI 拦住好。

4.3 大文件超过远端限制：远程仓库的“硬盘”报警

在 GitHub 上 push 文件超过 100MB 时，会看到：

text复制remote: error: File dist/libs.zip is 153.34 MB; this exceeds GitHub's file size limit of 100.00 MB
remote: error: GH001: Large files detected. You may want to try Git Large File Storage.

这个报错最难搞的地方在于：即使你马上删除这个文件再提交，Git 的历史里还留着它的记录，push 依然会被拒绝。需要清理的不只是当前工作区，而是所有提交历史。

简单场景下，如果大文件只是最近一次提交引入的，可以用：

bash复制git rm --cached dist/libs.zip
echo "dist/libs.zip" >> .gitignore
git commit --amend

如果文件已经存在于多轮提交里，就需要修改历史。推荐用 git filter-repo：

bash复制git filter-repo --path dist/libs.zip --invert-paths

跑完这个命令，这个文件会从所有历史提交里消失。但注意：重写历史后，所有协作者都需要重新克隆，或者用 git pull --rebase 同步，否则会把旧历史又推回来。

防止大文件进仓库，最好的办法是在 .gitignore 里提前排除，或者对大文件使用 Git LFS。GitHub 免费版支持 LFS 的存储空间有限，但总比历史里塞一个 150MB 压缩包来得强。

4.4 Windows 下文件被占用，commit 或 checkout 报 Permission denied

Windows 上跑 Git 遇到：

text复制error: unable to unlink old 'src/App.vue': Permission denied

多半是文件被 IDE、编辑器或某个进程锁住了。最常见的是 VSCode 开了文件，且终端就在 VSCode 里面。Git 想要覆盖工作区文件，但锁被占着，只好报错。

处理办法：

1. 保存并关闭所有编辑器窗口。
2. 关掉可能正在读取文件的进程，比如 npm run dev 或文件监听器。
3. 重试 git checkout 或 git pull。

如果实在找不到占用进程，可以用 Resource Monitor 资源监视器，在“CPU”页面搜进程句柄，输入文件名看看是谁占的。这个操作比重启电脑省时间得多。

5. 免密登录、SSH 密钥、Windows 专属疑难杂症

每天重复输入账号密码，是很多人又烦又没有真正下定决心解决的问题。免密配置看上去就是一条命令的事，但实际踩坑点不少，尤其是 SSH 密钥配好了还不生效的情况，十个人里有三四个是密钥格式和协议的问题。

5.1 HTTPS 方式下每次 push 都要输密码

如果你一直用 HTTPS 克隆仓库，每次 push 都要输用户名和 token，说明 Git 没有配置凭据存储。解决方式有三种，各有优劣：

直接设置：

bash复制git config --global credential.helper manager-core

在 Windows 上它会调用 Git Credential Manager，第一次输入凭据后会被安全地保存在系统的凭据管理器里，后续不再询问。如果你特别在意命令行输出，想用 token 直接贴在 URL 里，也可以：

bash复制git remote set-url origin https://<token>@github.com/username/repo.git

但这种方式 token 会出现在 git remote -v 里，截图时容易泄露，不推荐。

5.2 SSH 报 Permission denied (publickey)

SSH 免密是更干净的方式，第一次配的坑也不少。执行：

bash复制ssh -T git@github.com

如果返回：

text复制git@github.com: Permission denied (publickey).

那就说明公钥没有被远端识别。按这个顺序排查：

1. 确认本地有密钥对：

bash复制ls -l ~/.ssh

如果没有，生成一个：

bash复制ssh-keygen -t ed25519 -C "you@example.com"

一路回车即可。生成后打开公钥文件：

bash复制cat ~/.ssh/id_ed25519.pub

2. 把输出的整段公钥（以 ssh-ed25519 开头）复制到 GitHub 或 GitLab 的 SSH Keys 设置页里。
3. 再执行 ssh -T git@github.com，如果返回 Hi username! 就说明认证通过。

很多人的问题出在第三步之后的 git clone 地址上。如果克隆时仍然用 HTTPS 地址，SSH 密钥自然不生效。要改成 SSH 地址，执行：

bash复制git remote set-url origin git@github.com:username/repo.git

还有一种情况是 ssh-agent 没加载私钥。执行：

bash复制eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

如果你同时管理多个平台的多个密钥，建议在 ~/.ssh/config 里写清楚：

text复制Host github.com
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519_github

Host gitlab.com
  HostName gitlab.com
  User git
  IdentityFile ~/.ssh/id_ed25519_gitlab

5.3 TortoiseGit 连接异常：多半是 SSH 客户端选错了

Git 小乌龟作为 Windows 图形客户端确实方便，但它默认的 SSH 客户端可以选择，选错了就会出现“TortoiseGit 能打开，但拉取推送全部失败”的诡异情况。

典型的报错：

text复制Error: The server's host key is not cached in the registry.

解决步骤：

1. 打开 TortoiseGit 设置。
2. 进入“网络”标签。
3. 把“SSH 客户端”从默认的 TortoiseGitPLink.exe 改成 Git 自带的 SSH 客户端：

text复制C:\Program Files\Git\usr\bin\ssh.exe

改完重新测试连接。很多看似复杂的问题，其实就是这里选错了。

5.4 VSCode 里 Git 凭据一直弹，输什么都说失败

VSCode 内置 Git 插件，但它的凭据来源其实是 Git Credential Manager。如果系统凭据管理器里存了一个旧 token，VSCode 会一直用旧 token 去认证，弹窗里你输入新 token，它也不刷新。

处理办法，先清理系统里旧的 Git 凭据。在 CMD 里运行：

bash复制cmdkey /list | findstr /i git

看到类似 git:https://github.com 的条目，删除：

bash复制cmdkey /delete:git:https://github.com

然后重新打开 VSCode，触发一次 push，它会重新弹出登录框，输入新 token 即可。如果 VSCode 仍然卡在“正在打开身份验证”状态，可以试着重启 VSCode 或者执行：

bash复制git config --global --unset credential.helper

再重新设置一次 manager-core。这个操作等于让凭据管理器把旧缓存全部作废，重新走一轮认证流程。

6. 遇到陌生报错时，我的排查顺序和几个“不要做”

前面这些是高频报错的固定解法，但 Git 的报错种类实在太多。就算经验再丰富，也总有没见过的新问题。我自己的习惯是：不急着找“一键修复”，先按固定流程把现场探清楚。

6.1 先别慌，按这个顺序排查

拿到一条陌生报错，我通常会做四件事：

第一步，完整复制报错原文。不要只看最后一行，报错文本的前半段往往包含关键文件路径和错误码。比如 fatal: unable to access 和 fatal: Authentication failed 看起来都像“远程失败”，但一个是网络层，一个是认证层，方向完全不同。

第二步，检查当前仓库状态和全局配置：

bash复制git status
git remote -v
git config --list --show-origin

--show-origin 会告诉你某个配置来自哪个文件，是全局的还是仓库级的，排查时特别有用。很多奇怪行为都是配置覆盖导致的，比如仓库级配置里设置了错误的代理，全局却是干净的，光看全局配置根本发现不了。

第三步，做最小复现。新建一个空目录，执行 git init，模拟同样的操作。如果最小复现里不报错，说明问题出在项目本身或仓库历史，而不是 Git 环境。

第四步，拿着完整报错去搜索。搜索时优先搜报错第一行，比如 fatal: A URL-encoded or filename...，而不是“Git push 失败”这种含糊说法。

6.2 这些命令能不用就不用

网上很多“万能命令”不仅不万能，还会带来新的灾难。我列三个风险最高的：

--force-with-lease 我特别推荐，它在推送前会检查远端是否有了新的提交，如果有就拒绝推送，等于给强力操作加了一道保险。

另一个容易出问题的是：

bash复制git config --global http.sslVerify false

这条命令我在前面提过，它能让证书问题瞬间消失，但也让所有 HTTPS 仓库的传输变成“裸奔”。真要临时用，也要放在仓库级配置里，问题解决后马上移除。

6.3 定期健康检查让 Git 仓库更稳定

最后分享一个维护习惯。项目跑了几个月后，偶尔会遇到一些莫名其妙的“对象缺失”错误，比如：

text复制error: object file .git/objects/... is empty

这通常不是操作问题，而是仓库本身的 Git 对象文件损坏。这时候可以执行：

bash复制git fsck --full

检查有没有坏对象，如果没有严重问题，再执行：

bash复制git gc --prune=now

这个命令会清理过期的对象文件，让仓库变得更紧凑。执行前确认你没有正在运行的操作，老式 HDD 上如果仓库特别大，可能要等一会。日常开发中，git remote prune origin 也是个好习惯，它会清理远端已经删除的分支引用，避免本地残留一堆 no longer exists 的远端分支。

我在实际使用中的体会是：Git 的大多数报错都不是“Git 坏了”，而是操作环境和仓库状态超出了 Git 的默认预期。只要冷静下来，把报错拆成“环境、网络、仓库状态、钩子”这四个维度，80% 的问题都能在十分钟内定位。建议收藏这份清单，遇到问题别急着复制网上命令，先对照一下这里面的排查链路，往往比乱试一通更省时间。