0 引言

在日常開(kāi)發(fā)中，我們常常會(huì)遇到 Git 推送失敗的問(wèn)題，尤其是在初次配置遠(yuǎn)程倉(cāng)庫(kù)或網(wǎng)絡(luò)環(huán)境受限的情況下。

如會(huì)出現(xiàn)類(lèi)似如下的報(bào)錯(cuò)：

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

本文將詳細(xì)介紹如何通過(guò)配置 SSH 協(xié)議解決 Git 推送失敗問(wèn)題，并深入解析一個(gè)常見(jiàn)的錯(cuò)誤場(chǎng)景：“fatal: refusing to merge unrelated histories”。

1 SSH 配置詳解

1.1 為什么選擇 SSH？

Git 支持 HTTPS 和 SSH 兩種協(xié)議進(jìn)行遠(yuǎn)程通信：

• HTTPS：需要每次輸入用戶名和密碼（或使用 token），容易受代理影響。
• SSH：基于密鑰認(rèn)證，安全高效，且不受部分代理干擾，適合長(zhǎng)期開(kāi)發(fā)使用。

1.2 生成 SSH 密鑰對(duì)

如果你尚未配置 SSH 密鑰，可以在 Git Bash 通過(guò)以下命令生成并配置 SSH 密鑰：

ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

• -t rsa 表示使用 RSA 算法。
• -b 4096 表示密鑰長(zhǎng)度為 4096 位，更安全。
• -C 后面是注釋?zhuān)ㄗh填寫(xiě)注冊(cè) GitHub 的郵箱。

系統(tǒng)會(huì)提示：

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

直接回車(chē)即可（使用默認(rèn)路徑 /c/Users/XXX/.ssh/id_rsa）

接著會(huì)提示：

Enter passphrase (empty for no passphrase):

可以選擇輸入一個(gè)密碼（推薦），會(huì)要求二次輸入確認(rèn)，也可以直接按回車(chē)跳過(guò)。

成功后會(huì)顯示：

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

執(zhí)行以下命令顯示公鑰內(nèi)容：

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

輸出類(lèi)似如下內(nèi)容（以 ssh-rsa 開(kāi)頭）：

ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQC7... your_email@example.com

完整復(fù)制輸出內(nèi)容，在 GitHub SSH Keys 設(shè)置頁(yè)面 中添加新密鑰。

點(diǎn)擊New Key，填寫(xiě)Title，將復(fù)制的內(nèi)容粘貼進(jìn) Key 文本框，最后點(diǎn)擊 Add SSH key。

1.4 測(cè)試 SSH 連接

運(yùn)行以下命令測(cè)試是否成功連接 GitHub：

ssh -T git@github.com

如果返回如下提示，則表示 SSH 已配置成功：

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

如果提示主機(jī)指紋未知，請(qǐng)確認(rèn)是否為官方服務(wù)器，并輸入 yes 繼續(xù)連接。

當(dāng)?shù)谝淮螄L試連接 GitHub 的 SSH 服務(wù)，系統(tǒng)為了安全起見(jiàn)會(huì)提示你確認(rèn) GitHub 的主機(jī)密鑰指紋：

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即可。

然后會(huì)提示你輸入 passphrase（如果你在生成密鑰時(shí)設(shè)置了密碼），否則直接回車(chē)即可。

1.5 修改遠(yuǎn)程倉(cāng)庫(kù)地址為 SSH 格式

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

git remote set-url origin git@github.com:username/repo.git

驗(yàn)證當(dāng)前遠(yuǎn)程地址：

git remote -v

接著就能進(jìn)行clone或push等操作了。

2 遠(yuǎn)程倉(cāng)庫(kù)推送失敗問(wèn)題解決

2.1 報(bào)錯(cuò)信息示例

我在執(zhí)行推送命令時(shí)報(bào)錯(cuò)：

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 原因分析

該錯(cuò)誤通常表示遠(yuǎn)程分支存在本地沒(méi)有的提交記錄（unrelated histories） ，可能原因分析如下：

1. 其他開(kāi)發(fā)者在 GitHub 上向 main 分支提交并推送了新的代碼；
2. 你在其他設(shè)備上提交過(guò)代碼但沒(méi)同步回來(lái)；
3. 遠(yuǎn)程倉(cāng)庫(kù)初始化時(shí)已包含文件（如 README.md）。

此時(shí) Git 無(wú)法直接合并兩個(gè)不同歷史起點(diǎn)的分支。

我的例子是我在本地初始化了一個(gè)新的 Git 倉(cāng)庫(kù)（git init），接著添加了遠(yuǎn)程倉(cāng)庫(kù)地址；
然后我執(zhí)行 git pull origin；
main 想要拉取遠(yuǎn)程分支內(nèi)容； 但由于本地和遠(yuǎn)程是完全獨(dú)立的倉(cāng)庫(kù)（沒(méi)有任何共同提交歷史），Git 默認(rèn)拒絕合并它們。

2.3 解決方法：拉取遠(yuǎn)程并合并不相關(guān)歷史

2.3.1 允許合并不相關(guān)歷史

git pull origin main --allow-unrelated-histories

此參數(shù)用于強(qiáng)制 Git 合并兩個(gè)沒(méi)有共同祖先的提交歷史。

2.3.2 解決沖突（如有）

如果提示沖突，檢查狀態(tài)并處理沖突:

git status

添加文件并提交：

git add .
git commit -m "合并遠(yuǎn)程倉(cāng)庫(kù)到本地"

2.3.3 推送至遠(yuǎn)程

git push origin main

到此這篇關(guān)于使用SSH協(xié)議解決Git推送失敗問(wèn)題的具體操作方法的文章就介紹到這了,更多相關(guān)SSH協(xié)議解決Git推送失敗內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！