首页/Git/常见报错

Git 常见报错速查

开发中常遇到的 Git 报错信息，快速定位原因和解决方案。

Permission denied (publickey)

出现场景：git push 或 git clone 时

原因：SSH 密钥未配置或未添加到 GitHub/GitLab

解决方案：

  1. 检查是否有 SSH 密钥：ls ~/.ssh/id_*.pub
  2. 没有则生成：ssh-keygen -t ed25519 -C "your@email.com"
  3. 将公钥添加到 GitHub：cat ~/.ssh/id_ed25519.pub → GitHub Settings → SSH Keys
  4. 测试连接：ssh -T git@github.com

预防：配置 SSH agent 自动加载密钥：eval $(ssh-agent) && ssh-add

CONFLICT (content): Merge conflict in <file>

出现场景：git merge 或 git pull 时

原因：两个分支修改了同一文件的同一位置

解决方案：

  1. 打开冲突文件，找到 <<<<<<< / ======= / >>>>>>> 标记
  2. 手动编辑保留需要的内容，删除冲突标记
  3. git add <file> 标记为已解决
  4. git commit 完成合并

预防：频繁从主分支拉取更新，减少分支存活时间

You are in 'detached HEAD' state

出现场景：git checkout <commit-hash> 后

原因：HEAD 指向了一个具体的 commit 而非分支

解决方案：

  1. 如果只是查看：看完后 git checkout main 回到分支
  2. 如果要保留修改：git checkout -b new-branch 创建新分支
  3. 如果已经提交了：git branch new-branch 然后 git checkout new-branch

预防：用 git checkout <branch> 而非 commit hash，除非确实需要查看历史

! [rejected] main -> main (non-fast-forward)

出现场景：git push 时

原因：远程有你本地没有的提交（别人先推送了）

解决方案：

  1. 先拉取再推送：git pull --rebase origin main && git push
  2. 或者：git fetch origin && git rebase origin/main && git push
  3. 如果确定要覆盖远程（危险）：git push --force-with-lease

预防：推送前先 git pull --rebase，养成习惯

remote: error: File xxx is 123.45 MB; this exceeds GitHub's file size limit

出现场景：git push 大文件时

原因：GitHub 限制单文件不超过 100MB

解决方案：

  1. 从历史中移除大文件：git filter-branch --force --index-filter 'git rm --cached --ignore-unmatch <file>' HEAD
  2. 或用 BFG Repo-Cleaner（更快）：bfg --strip-blobs-bigger-than 100M
  3. 以后用 Git LFS 管理大文件：git lfs track '*.psd'
  4. 添加到 .gitignore 防止再次提交

预防：在 .gitignore 中排除大文件，使用 Git LFS 管理二进制资源