使用SSH协议解决Git推送失败问题的具体操作做法实用指南

平时做技术实践时，很多问题不是概念不会，而是细节没串起来。拿“采用SSH协议解决Git推送失败问题的具体操作做法”来说，它看着像小点，放到项目里常会牵出环境、配置、兼容性和维护成本。下面按实际采用顺序，把思路、关键写法和容易踩坑的地方讲清楚，便于大家直接对照操作。

0 引言

实际处理时，在日常开发里，我们常常会遇到 Git 推送失败的问题，尤其是在初次设置远程仓库或网络环境受限的情况下。

如会出现类似如下所示的报错：

fatal: unable to access 'https://github.com/username/repo.git/': Recv failure: Connection was reset

落到代码里，下面会系统梳理如何借助设置 SSH 协议解决 Git 推送失败问题，并深入解析一个常用的错误场景：“fatal: refusing to merge unrelated histories”。

1 SSH 设置详解

1.1 为什么选择 SSH？

Git 兼容 HTTPS 和 SSH 两种协议进行远程通信：

• HTTPS：需每次输入用户名和密码（或采用 token），容易受代理影响。
• SSH：基于密钥认证，安全高效，且不受部分代理干扰，适合长期开发采用。

1.2 生成 SSH 密钥对

从实现思路看，若你尚未设置 SSH 密钥，能够在 Git Bash 借助以下命令生成并设置 SSH 密钥：

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

• -t rsa 表示采用 RSA 算法。
• -b 4096 表示密钥长度为 4096 位，更安全。
• -C 后面是注释，建议填写注册 GitHub 的邮箱。

系统会提示：

Generating public/private rsa key pair.
Enter file in which to save the key (/c/Users/XXX/.ssh/id_rsa):

直接回车即可（采用默认路径 /c/Users/XXX/.ssh/id_rsa）

接着会提示：

Enter passphrase (empty for no passphrase):

结合项目来看，能够选择输入一个密码（建议），会要求二次输入确认，也能够直接按回车跳过。

成功后会显示：

Your identification has been saved in /c/Users/XXX/.ssh/id_rsa
Your public key has been saved in /c/Users/XXX/.ssh/id_rsa.pub
The key fingerprint is:
SHA256:XXXXXXXXXXXXXXXXX [email protected]
The key's randomart image is:
XXXXXXXXXX
XXXXXXXXXX
XXXXXXXXXX
……

1.3 添加公钥到 GitHub

执行以下命令显示公钥内容：

cat /c/Users/XXX/.ssh/id_rsa.pub

输出类似如下所示内容（以 ssh-rsa 开头）：

ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQC7... [email protected]

在这个场景下，完整复制输出内容，在 GitHub SSH Keys 设置页面 中添加新密钥。

从实现思路看，点击New Key，填写Title，将复制的内容粘贴进 Key 文本框，最后点击 Add SSH key。

1.4 测试 SSH 连接

运行以下命令测试是否成功连接 GitHub：

ssh -T [email protected]

若得到如下所示提示，则表示 SSH 已设置成功：

Hi username! You've successfully authenticated, but GitHub does not provide shell access.

落到代码里，若提示主机指纹未知，请确认是否为官方服务器，同时输入 yes 继续连接。

实际处理时，当第一次尝试连接 GitHub 的 SSH 服务，系统为了安全起见会提示你确认 GitHub 的主机密钥指纹：

The authenticity of host 'github.com (20.205.243.166)' can't be established.
ED25519 key fingerprint is SHA256:+DiY3wvvV6TuJJhbpZisF/zLDA0zPMSvHdkr4UvCOqU.
This key is not known by any other names.
Are you sure you want to continue connecting (yes/no/[fingerprint])?

输入yes即可。

在这个场景下，随后会提示你输入 passphrase（如果你在生成密钥时设置了密码），否则直接回车即可。

1.5 修改远程仓库地址为 SSH 格式

若之前用的是 HTTPS 地址，需改成 SSH：

git remote set-url origin [email protected]:username/repo.git

验证当前远程地址：

git remote -v

接着就能进行clone或push等操作了。

2 远程仓库推送失败问题解决

2.1 报错信息示例

我在执行推送命令时报错：

error: failed to push some refs to 'github.com:username/repo.git'
hint: Updates were rejected because the remote contains work that you do not have locally.

2.2 原因分析

结合项目来看，该错误通常表示远程分支存在本地没有的提交记录（unrelated histories），可能原因分析如下所示：

1. 其他开发者在 GitHub 上向 main 分支提交同时推送了新的代码；
2. 你在其他设备上提交过代码但没同步回来；
3. 远程仓库初始化时已包含文件（如 README.md）。

此时 Git 无法直接合并两个不同历史起点的分支。

在这个场景下，我的例子是我在本地初始化了一个新的 Git 仓库（git init），接着添加了远程仓库地址；
然后我执行 git pull origin；
在这个场景下，main 想要拉取远程分支内容； 但由于本地和远程是完全独立的仓库（没有任何共同提交历史），Git 默认拒绝合同时它们。

2.3 解决方法：拉取远程并合并不相关历史

2.3.1 允许合并不相关历史

git pull origin main --allow-unrelated-histories

此参数用来强制 Git 合同时两个没有共同祖先的提交历史。

2.3.2 解决冲突（如有）

如果提示冲突，检查状态并处理冲突:

git status

添加文件并提交：

git add .
git commit -m "合并远程仓库到本地"

2.3.3 推送至远程

git push origin main

到此这篇关于采用SSH协议解决Git推送失败问题的具体操作方法的文章就介绍到这了,更多相关SSH协议解决Git推送失败内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多兼容脚本之家！