Git代码提交失败？手把手教你排查与解决

一、问题/场景描述

在日常开发中，使用Git进行代码提交是常见操作。但不少开发者会遇到 git commit 或 git push 失败的情况，例如提示权限拒绝、文件冲突、钩子脚本错误等。这类错误会中断工作流，影响效率。本文系统梳理了Git代码提交失败的典型原因，并提供详细解决步骤，帮助开发者快速恢复提交。

二、原因分析

Git代码提交失败通常由以下几类原因引起：

1. 权限问题：远程仓库的SSH密钥未配置或失效、HTTPS认证失败、没有写入权限。
2. 文件冲突：本地分支与远程分支存在冲突，导致 push 被拒绝。
3. 钩子脚本错误：客户端或服务端的Git钩子（如pre-commit、pre-push）执行失败。
4. 仓库状态异常：未暂存文件、未解决冲突、索引锁定等。
5. 网络或服务端问题：远程仓库不可达、磁盘空间不足。

三、详细解决步骤

步骤1：检查权限配置

首先确认SSH密钥是否已添加。运行以下命令测试连接：

ssh -T [email protected]

若提示权限拒绝，请重新生成SSH密钥并添加到GitHub/GitLab：

ssh-keygen -t rsa -b 4096 -C "[email protected]"

cat ~/.ssh/id_rsa.pub

将输出的公钥复制到远程仓库的SSH设置中。若使用HTTPS，请检查凭据：

git config --global credential.helper store

git push https://github.com/username/repo.git

步骤2：处理文件冲突

当 git push 失败提示“非快进”时，说明远程有更新。先拉取并合并：

git pull origin main

解决冲突后，重新提交：

git add .

git commit -m "解决冲突"

git push origin main

步骤3：检查钩子脚本

若提交时遇到“pre-commit hook failed”，请检查 .git/hooks/pre-commit 文件。临时跳过钩子：

git commit --no-verify -m "跳过钩子"

永久禁用钩子需删除或重命名文件：

mv .git/hooks/pre-commit .git/hooks/pre-commit.bak

步骤4：修复仓库状态异常

若提示“index.lock”文件存在，删除锁定文件：

rm -f .git/index.lock

若存在未解决的冲突，使用 git status 查看并手动编辑文件，然后：

git add <冲突文件>

git commit -m "解决冲突"

步骤5：网络与服务端排查

测试远程仓库连通性：

ping github.com

若使用代理，配置Git代理：

git config --global http.proxy http://127.0.0.1:7890

git config --global https.proxy http://127.0.0.1:7890

四、注意事项

在执行 git push --force 前务必谨慎，它会覆盖远程历史，可能导致他人丢失代码。建议使用 git push --force-with-lease 作为更安全的替代。另外，定期清理 .git 目录中的临时文件，避免索引锁定。如果问题持续，检查远程仓库的磁盘空间和权限设置。

五、适用环境

本文适用于 Git 2.x 及以上版本，操作系统不限（Windows/macOS/Linux），远程仓库支持 GitHub、GitLab、Gitee 等常见平台。