网站 租用服务器seo网站建设

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 "your_email@example.com"

• -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 your_email@example.com
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... your_email@example.com

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

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

1.4 测试 SSH 连接

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

ssh -T git@github.com

如果返回如下提示，则表示 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（如果你在生成密钥时设置了密码），否则直接回车即可。

来源：GitHub 官方公布的 ED25519 指纹

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

如果之前用的是 HTTPS 地址，需要改成 SSH：

git remote set-url origin git@github.com: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

3 参考资料

GitHub 官方文档：Connecting to GitHub with SSH
Git 官方手册：git-pull Documentation