2939 words
15 minutes
Git 常见问题整理

持续更新 Git 日常使用中的高频报错与解决办法。本文尽量按照报错原文 + 常见原因 + 解决办法的形式整理,适合作为排错速查表。

先记住这 4 个通用排查命令#

很多 Git 报错看起来不一样,但排查思路很像。遇到问题时,先跑下面 4 条命令,通常能先定位一半:

Terminal window
git status
git branch -vv
git remote -v
git log --oneline --graph --decorate -n 10
  • git status:看工作区、暂存区、冲突状态
  • git branch -vv:看当前分支跟踪的是哪个远程分支、是否领先或落后
  • git remote -v:看远程地址到底是 https 还是 ssh
  • git log --oneline --graph --decorate -n 10:看提交历史是否分叉

1. git push 报错:RPC failed; HTTP 400 curl 22#

报错信息#

Terminal window
error: RPC failed; HTTP 400 curl 22 The requested URL returned error: 400

常见原因#

这个问题通常出现在以下几种场景中:

  • 一次推送的数据包过大
  • 网络不稳定,导致上传中断
  • 使用 HTTP 推送时,缓冲区不足

本质上可以先理解为:Git 在打包并上传对象时失败了

解决办法#

核心思路很简单:把缓冲区调大

HTTP#

Terminal window
git config http.postBuffer 524288000

如果你希望这个设置作用于所有仓库,也可以改成:

Terminal window
git config --global http.postBuffer 524288000

SSH#

有些资料会给出下面这条命令:

Terminal window
git config ssh.postBuffer 524288000

不过需要注意:Git 并没有通用的 ssh.postBuffer 配置项。如果你使用的是 SSH 地址推送,优先建议检查网络、仓库中的大文件,或者先确认是否其实仍然在走 HTTP 方式上传。

推荐排查顺序#

  1. 先执行 git remote -v,确认远程仓库地址是 http(s) 还是 ssh
  2. 如果是 HTTP,优先执行 git config http.postBuffer 524288000
  3. 重新执行 git push
  4. 如果仍然失败,再检查是否存在超大文件、代理问题或远程仓库限制

补充说明#

  • 524288000 约等于 500 MB
  • 这个办法主要用于缓解大包推送导致的失败,不是所有 HTTP 400 的万能解法
  • 如果仓库里包含大文件,长期更推荐使用 Git LFS

2. push 被拒绝:failed to push some refs / non-fast-forward#

报错信息#

Terminal window
error: failed to push some refs to 'origin'
! [rejected] main -> main (non-fast-forward)

常见原因#

  • 远程分支比本地更新
  • 别人已经先推送了新的提交
  • 本地提交历史和远程分支发生分叉

解决办法#

先把远程最新提交拉下来,再推送:

Terminal window
git pull --rebase origin main
git push origin main

如果你本来就在做历史改写(比如 rebase 之后重新推送),优先使用更安全的方式:

Terminal window
git push --force-with-lease origin main

注意#

不要上来就直接 git push --force。多人协作时,这很容易把别人的提交顶掉。


3. src refspec does not match any#

报错信息#

Terminal window
error: src refspec main does not match any

常见原因#

  • 分支名写错了
  • 当前仓库还没有任何提交
  • 你以为当前分支叫 main,实际可能还是 master

解决办法#

先确认当前分支:

Terminal window
git branch

如果仓库还没有第一次提交,先提交一次:

Terminal window
git add .
git commit -m "init"
git push -u origin main

4. fatal: not a git repository#

报错信息#

Terminal window
fatal: not a git repository (or any of the parent directories): .git

常见原因#

  • 当前目录不是 Git 仓库
  • 你进入了错误的目录
  • .git 目录被删了

解决办法#

Terminal window
pwd
ls -la

确认路径正确后再执行 Git 命令;如果这是一个新目录,就初始化:

Terminal window
git init

5. remote origin already exists#

报错信息#

Terminal window
fatal: remote origin already exists.

常见原因#

你已经添加过名为 origin 的远程仓库,又重复执行了 git remote add origin ...

解决办法#

先查看远程:

Terminal window
git remote -v

如果只是地址变了,直接改地址即可:

Terminal window
git remote set-url origin <new-url>

如果你就是想重建它:

Terminal window
git remote remove origin
git remote add origin <new-url>

6. ‘origin’ does not appear to be a git repository#

报错信息#

Terminal window
fatal: 'origin' does not appear to be a git repository
fatal: Could not read from remote repository.

常见原因#

  • 远程地址写错了
  • 远程仓库不存在
  • 你没有访问权限
  • 远程名称不是 origin

解决办法#

先检查远程配置:

Terminal window
git remote -v

如果地址不对,修正:

Terminal window
git remote set-url origin <correct-url>

7. HTTPS 认证失败:Authentication failed#

报错信息#

Terminal window
fatal: Authentication failed for 'https://github.com/xxx/xxx.git/'

常见原因#

  • 用户名或密码错误
  • 平台不再支持账号密码推送,只能用 Token
  • 凭据缓存了旧密码

解决办法#

  1. 确认远程地址是否为 HTTPS:git remote -v
  2. 改用 Personal Access Token
  3. 清理本机缓存的旧凭据后重新认证

如果你不想每次处理 HTTPS 凭据,也可以直接切换成 SSH:

Terminal window
git remote set-url origin [email protected]:owner/repo.git

8. SSH 认证失败:Permission denied (publickey)#

报错信息#

Terminal window
Permission denied (publickey).
fatal: Could not read from remote repository.

常见原因#

  • 本机没有 SSH key
  • SSH key 没有添加到 GitHub/GitLab
  • SSH agent 没加载私钥
  • 远程仓库地址是 SSH,但当前账号没有权限

解决办法#

生成新 key:

Terminal window
ssh-keygen -t ed25519 -C "[email protected]"

加入 agent:

Terminal window
ssh-add ~/.ssh/id_ed25519

然后把公钥内容添加到平台:

Terminal window
cat ~/.ssh/id_ed25519.pub

9. Host key verification failed#

报错信息#

Terminal window
Host key verification failed.

常见原因#

  • 本地记录的服务器指纹变了
  • 你之前连过一个旧主机
  • known_hosts 中的记录过期或冲突

解决办法#

删除旧记录后重新连接:

Terminal window
ssh-keygen -R github.com

然后重新测试:

Terminal window

10. Could not resolve host#

报错信息#

Terminal window
fatal: unable to access 'https://github.com/owner/repo.git/': Could not resolve host: github.com

常见原因#

  • 网络断开
  • DNS 解析异常
  • 代理配置错误
  • 远程地址拼写错误

解决办法#

Terminal window
git remote -v
ping github.com

如果远程地址没问题,就重点检查网络、DNS、代理。


11. SSL certificate problem: unable to get local issuer certificate#

报错信息#

Terminal window
fatal: unable to access 'https://github.com/owner/repo.git/': SSL certificate problem: unable to get local issuer certificate

常见原因#

  • 公司代理替换了 HTTPS 证书
  • 系统 CA 证书不完整
  • 本机证书链异常

解决办法#

  • 优先修复系统证书或公司代理证书链
  • 或者改用 SSH 地址推送
Terminal window
git remote set-url origin [email protected]:owner/repo.git

注意#

临时关闭 SSL 校验虽然能“过”,但不建议长期使用:

Terminal window
git config --global http.sslVerify false

这是临时排查手段,不是推荐方案。


12. pathspec did not match any file(s) known to git#

报错信息#

Terminal window
error: pathspec 'xxx' did not match any file(s) known to git

常见原因#

  • 分支名写错了
  • 文件路径写错了
  • 目标文件根本不存在

解决办法#

先判断你是在切分支还是操作文件:

Terminal window
git branch --all
ls

如果是分支问题,就用真实分支名;如果是文件问题,就检查路径拼写。


13. detached HEAD#

报错信息#

Terminal window
You are in 'detached HEAD' state.

常见原因#

你直接 checkout 到某个 commit、tag,而不是某个分支。

解决办法#

如果只是临时查看,切回正常分支即可:

Terminal window
git switch main

如果你已经在 detached HEAD 上做了修改,并且想保留:

Terminal window
git switch -c fix-from-detached-head

14. Merge conflict / Rebase conflict#

报错信息#

Terminal window
CONFLICT (content): Merge conflict in <file>

或者文件里出现:

<<<<<<< HEAD
=======
>>>>>>> other-branch

常见原因#

同一段代码被两个分支改了,Git 无法自动合并。

解决办法#

  1. 手动编辑冲突文件
  2. 删除冲突标记
  3. 保留正确内容
  4. 标记为已解决
Terminal window
git add <file>

如果你正在 merge:

Terminal window
git commit

如果你正在 rebase:

Terminal window
git rebase --continue

15. Your local changes would be overwritten by merge#

报错信息#

Terminal window
error: Your local changes to the following files would be overwritten by merge:

常见原因#

你本地有未提交修改,Git 担心 pull/merge 后把这些内容覆盖掉。

解决办法#

要么先提交:

Terminal window
git add .
git commit -m "save local work"

要么先暂存:

Terminal window
git stash
git pull
git stash pop

16. Untracked working tree files would be overwritten by merge#

报错信息#

Terminal window
error: Untracked working tree file 'xxx' would be overwritten by merge.

常见原因#

你的工作区里存在未被 Git 跟踪的文件,而远程或目标分支里正好也有同名文件。

解决办法#

先处理这些未跟踪文件:

Terminal window
git status

根据情况选择:

  • 备份后删除
  • 加入版本控制
  • 移动到别处
  • 加入 .gitignore

17. refusing to merge unrelated histories#

报错信息#

Terminal window
fatal: refusing to merge unrelated histories

常见原因#

  • 本地仓库和远程仓库不是同一条历史
  • 常见于“本地先 git init,远程也单独建了 README”
  • 或者你在合并两个完全不同来源的仓库

解决办法#

确认你就是要合并两条独立历史,再执行:

Terminal window
git pull origin main --allow-unrelated-histories

18. index.lock 已存在#

报错信息#

Terminal window
fatal: Unable to create '.git/index.lock': File exists.

常见原因#

  • 上一个 Git 命令异常中断
  • 有另一个 Git 进程还在运行
  • 残留锁文件没有清理

解决办法#

先确认没有别的 Git 进程在跑,再删除锁文件:

Terminal window
rm -f .git/index.lock

19. cannot lock ref#

报错信息#

Terminal window
error: cannot lock ref 'refs/heads/main'

常见原因#

  • 有并发 Git 进程
  • .git/refs 中有脏锁文件
  • 分支引用损坏
  • 文件系统权限异常

解决办法#

  1. 关闭其他 Git 进程
  2. 检查 .git 目录权限
  3. 清理对应 lock 文件
  4. 必要时执行一次:
Terminal window
git fetch --prune

20. ambiguous argument#

报错信息#

Terminal window
fatal: ambiguous argument 'xxx': unknown revision or path not in the working tree.

常见原因#

  • 分支名写错
  • tag 名写错
  • commit hash 不存在
  • Git 无法判断你给的是“路径”还是“引用”

解决办法#

先检查引用是否存在:

Terminal window
git branch --all
git tag
git log --oneline --all | head

如果你传的是文件路径,可以用 -- 显式分隔:

Terminal window
git log -- README.md

21. bad object#

报错信息#

Terminal window
fatal: bad object <hash>

常见原因#

  • 输入了错误的 commit hash
  • 本地对象缺失
  • 仓库对象损坏

解决办法#

先确认对象是否真的存在:

Terminal window
git show <hash>

如果不存在,先 fetch

Terminal window
git fetch --all --prune

如果怀疑仓库损坏,可进一步检查:

Terminal window
git fsck

22. detected dubious ownership in repository#

报错信息#

Terminal window
fatal: detected dubious ownership in repository at '/path/to/repo'

常见原因#

  • 仓库目录所有者和当前执行用户不一致
  • 常见于共享目录、Docker 挂载目录、管理员权限切换后

解决办法#

如果你确认这个目录可信,可以加入安全目录:

Terminal window
git config --global --add safe.directory /path/to/repo

23. LF will be replaced by CRLF#

报错信息#

Terminal window
warning: LF will be replaced by CRLF in <file>

常见原因#

不同操作系统的换行符不一致:

  • Linux / macOS 常用 LF
  • Windows 常用 CRLF

解决办法#

Windows 常见配置:

Terminal window
git config --global core.autocrlf true

macOS / Linux 常见配置:

Terminal window
git config --global core.autocrlf input

如果团队有统一规范,最好配合 .gitattributes 一起管理。


24. shallow update not allowed#

报错信息#

Terminal window
shallow update not allowed

常见原因#

你当前仓库是浅克隆(--depth),历史不完整,某些推送或同步操作会被拒绝。

解决办法#

补全历史:

Terminal window
git fetch --unshallow

如果仓库很大,也可以按需拉深:

Terminal window
git fetch --depth=100

25. pull —rebase 时提示有未暂存修改#

报错信息#

Terminal window
error: cannot pull with rebase: You have unstaged changes.
error: please commit or stash them.

常见原因#

你在本地改了文件,但还没提交或 stash,Git 不允许直接 rebase。

解决办法#

Terminal window
git add .
git commit -m "save work"
git pull --rebase

或者:

Terminal window
git stash
git pull --rebase
git stash pop

最后给一个排错顺序#

如果你不想一个个猜,建议按这个顺序查:

  1. git status:先看是不是本地工作区问题
  2. git branch -vv:看当前分支和远程分支关系
  3. git remote -v:确认到底是 HTTP 还是 SSH
  4. git fetch --all --prune:同步远程信息
  5. 认证相关就查 Token / SSH key / 权限
  6. 历史相关就查 rebase / merge / non-fast-forward
  7. 文件相关就查 pathspec / overwrite / 冲突

后续还可以继续补充的专题#

后面还可以继续单独展开这些专题:

  • Git 回滚:resetrevertrestore 的区别
  • Git 历史改写:commit --amendrebase -i
  • Git 误删文件恢复
  • Git 大文件治理与 Git LFS
  • Git 分支协作规范
Git 常见问题整理
https://fuwari.vercel.app/posts/git-common-issues/
Author
Owen
Published at
2026-05-28
License
CC BY-NC-SA 4.0