0 引言

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

如會出現(xiàn)類似如下的報錯：

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

本文將詳細介紹如何通過配置 SSH 協(xié)議解決 Git 推送失敗問題，并深入解析一個常見的錯誤場景：“fatal: refusing to merge unrelated histories”。

1 SSH 配置詳解

1.1 為什么選擇 SSH？

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

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

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 的郵箱。

系統(tǒng)會提示：

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

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

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

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

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

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

點擊New Key，填寫Title，將復制的內(nèi)容粘貼進 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 繼續(xù)連接。

當?shù)谝淮螄L試連接 GitHub 的 SSH 服務，系統(tǒng)為了安全起見會提示你確認 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（如果你在生成密鑰時設(shè)置了密碼），否則直接回車即可。

1.5 修改遠程倉庫地址為 SSH 格式

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

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

驗證當前遠程地址：

git remote -v

接著就能進行clone或push等操作了。

2 遠程倉庫推送失敗問題解決

2.1 報錯信息示例

我在執(zhí)行推送命令時報錯：

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. 其他開發(fā)者在 GitHub 上向 main 分支提交并推送了新的代碼；
2. 你在其他設(shè)備上提交過代碼但沒同步回來；
3. 遠程倉庫初始化時已包含文件（如 README.md）。

此時 Git 無法直接合并兩個不同歷史起點的分支。

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

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

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

git pull origin main --allow-unrelated-histories

此參數(shù)用于強制 Git 合并兩個沒有共同祖先的提交歷史。

2.3.2 解決沖突（如有）

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

git status

添加文件并提交：

git add .
git commit -m "合并遠程倉庫到本地"

2.3.3 推送至遠程

git push origin main

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

最新評論