Sourcetree拉取报错？手把手教你配置SSH客户端解决gitee.com主机密钥问题

Sourcetree SSH密钥配置全攻略：告别“主机密钥未缓存”的困扰

如果你正在使用Sourcetree管理代码，尤其是在连接国内代码托管平台时，很可能在拉取或推送代码时，突然被一个关于“主机密钥未缓存”的错误提示拦住去路。这个错误看似复杂，其实核心在于SSH连接的信任机制没有建立好。对于国内开发者而言，使用Gitee等平台时，由于网络环境或客户端配置的差异，这个问题尤为常见。本文将从原理到实践，为你彻底拆解这个问题的来龙去脉，并提供一套从密钥生成、配置到问题排查的完整解决方案。无论你是刚接触Git的新手，还是希望优化工作流的老手，都能在这里找到清晰、可操作的指引。

1. 理解SSH连接与“主机密钥未缓存”错误

在深入操作之前，我们有必要先搞清楚这个错误究竟意味着什么。当你使用SSH协议连接远程服务器（比如Gitee的Git服务器）时，客户端（你的Sourcetree）需要验证服务器的身份，以防止“中间人攻击”。这种验证依赖于服务器的SSH主机密钥。

简单来说，每台SSH服务器都有一对或多对密钥（如RSA、ED25519）。当客户端首次连接时，服务器会出示其公钥指纹。客户端会提示你：“这个服务器的身份我从未见过，这是它的指纹，你信任它吗？”如果你选择信任（输入‘y’），客户端就会将这个服务器的公钥保存到本地一个名为 known_hosts 的文件中。此后每次连接，客户端都会比对服务器提供的密钥和 known_hosts 中存储的密钥是否一致，以此确认连接的是否是真正的目标服务器，而非伪装者。

Sourcetree报错信息中提到的 The host key is not cached for this server: gitee.com (port 22)，指的就是这个首次信任的环节没有完成。Sourcetree作为一个图形化工具，在某些情况下（特别是Windows系统上使用非系统自带SSH客户端时），可能无法像命令行那样弹出交互式提示让你输入‘y’，从而导致连接流程卡住。

注意：known_hosts 文件是一个纯文本文件，通常位于用户主目录的 .ssh 文件夹下（例如 C:\Users\你的用户名\.ssh\known_hosts 或 ~/.ssh/known_hosts）。手动编辑这个文件需要谨慎，错误的格式可能导致SSH连接问题。

那么，为什么命令行Git可以而Sourcetree不行呢？这通常与Sourcetree内部调用的SSH可执行文件路径有关。Sourcetree默认可能使用其内置的SSH客户端，或者指向了另一个SSH客户端，而这个客户端的 known_hosts 文件路径或行为与系统标准的不同。我们的解决方案，核心就是统一并正确配置Sourcetree所使用的SSH客户端，确保它能像命令行一样正常工作。

2. 生成与配置SSH密钥对

解决主机密钥问题的前提，是你已经拥有了一对可用的SSH密钥（公钥和私钥），并且公钥已经正确添加到了你的Gitee账户中。如果你已经完成这一步，可以跳过本节，直接进入第三节。如果没有，请跟随以下步骤。

2.1 选择并生成SSH密钥

目前，ED25519算法因其安全性高、密钥短、性能好而被广泛推荐。当然，传统的RSA算法（建议密钥长度至少2048位，推荐4096位）也完全兼容。我们将以ED25519为例进行演示。

使用Git Bash或系统终端生成密钥：

打开你的终端（Windows用户可以使用Git Bash，macOS/Linux用户使用系统终端），输入以下命令：

ssh-keygen -t ed25519 -C "your_email@example.com"

请将 "your_email@example.com" 替换为你注册Gitee时使用的邮箱，这个注释会帮助你在多个密钥中识别这个密钥的用途。

执行命令后，你会看到一系列提示：

1. “Enter file in which to save the key”: 询问你密钥文件的保存路径和名称。直接按回车键，会使用默认路径和默认文件名（id_ed25519 和 id_ed25519.pub）。
2. “Enter passphrase”: 为你的私钥设置一个密码。这是一个额外的安全层，即使私钥文件泄露，没有密码也无法使用。你可以设置一个强密码，也可以直接回车留空（不推荐，尤其是用于生产环境）。

命令执行成功后，你会在 ~/.ssh/ 目录下看到两个新文件：

• id_ed25519: 这是你的私钥，必须严格保密，绝不能分享给任何人。
• id_ed25519.pub: 这是你的公钥，可以安全地配置到Gitee等远程服务上。

2.2 将公钥添加到Gitee账户

生成密钥对后，需要将公钥内容告诉Gitee。

1. 复制公钥内容。在终端中，可以使用以下命令来显示并复制公钥（macOS/Linux用 pbcopy，Windows Git Bash可能需要用 clip 或手动复制）：

   # macOS
   cat ~/.ssh/id_ed25519.pub | pbcopy
   
   # Windows Git Bash (如果clip命令可用)
   cat ~/.ssh/id_ed25519.pub | clip
   
   # 或者直接显示，然后手动复制
   cat ~/.ssh/id_ed25519.pub
   

   复制以 ssh-ed25519 AAAAC3... 开头，以你的邮箱注释结尾的整行内容。

2. 登录Gitee，添加SSH公钥。

   • 进入 Gitee.com，点击右上角头像 -> 设置。
   • 在左侧菜单中找到 SSH公钥。
   • 在“添加公钥”页面，将刚才复制的公钥内容粘贴到“公钥”文本框中。
   • “标题”可以自定义，用于识别这台电脑（例如“我的办公电脑-ED25519”）。
   • 点击 确定 完成添加。

至此，你的本地SSH密钥和远程Gitee账户之间的信任关系已经建立了一半。接下来，我们需要确保Sourcetree能正确使用这些密钥。

3. 在Sourcetree中配置SSH客户端与密钥

这是解决“主机密钥未缓存”错误的核心步骤。我们需要引导Sourcetree使用我们系统标准的SSH客户端（通常是OpenSSH），并指向我们刚刚生成的密钥。

操作步骤如下：

1. 打开Sourcetree设置。启动Sourcetree，在顶部菜单栏找到 工具(Tools) -> 选项(Options)（在macOS上可能是 Sourcetree -> 偏好设置(Preferences)）。

2. 切换到“一般(General)”选项卡。在这里，找到 SSH客户端配置(SSH Client Configuration) 部分。

3. 选择SSH客户端。在 SSH客户端(SSH Client) 下拉菜单中，选择 OpenSSH。这是最通用、行为最可预测的选择，它能确保Sourcetree使用系统路径下的 ssh 命令，从而正确访问 ~/.ssh/ 目录下的 known_hosts 文件和你的私钥。

   • 备选方案：在某些旧版本或特定环境下，你也可以选择“PuTTY/Plink”，但这需要你额外配置Pageant来管理密钥，过程更复杂。对于绝大多数用户，OpenSSH是最佳选择。

4. 指定SSH密钥文件。这是关键一步！在同一设置页面，找到 SSH密钥(SSH Key) 的配置项。点击旁边的浏览按钮(...)，导航到你本地 .ssh 目录，选择你的私钥文件。

   • 如果你使用默认的ED25519密钥，就选择 id_ed25519 文件（注意，是没有 .pub 后缀的那个）。
   • 如果你使用RSA密钥，就选择 id_rsa 文件。
   • 重要提示：Sourcetree这里需要的是私钥，而不是公钥文件。

5. 保存并应用。点击 确定(OK) 或 应用(Apply) 保存设置。

为了更清晰地展示不同SSH客户端选项的差异，可以参考下表：

配置项	选项：OpenSSH	选项：PuTTY/Plink	说明与推荐
SSH客户端	使用系统自带的 ssh 命令	使用 plink.exe (PuTTY工具链)	推荐OpenSSH，与系统命令行行为一致，兼容性好。
密钥管理	直接读取 ~/.ssh/ 下的标准密钥文件	通常需要借助Pageant加载.ppk格式的私钥	OpenSSH方式更直接，无需额外工具转换密钥格式。
known_hosts 文件	使用标准路径 ~/.ssh/known_hosts	可能使用独立文件或不同机制	OpenSSH能确保主机密钥缓存到标准位置，一劳永逸。
适用场景	绝大多数情况，尤其是使用系统生成的标准密钥	历史遗留项目或特定企业环境要求使用PuTTY	除非有强制要求，否则新手和大多数开发者应选择OpenSSH。

完成以上配置后，Sourcetree就已经被设定为使用和你命令行相同的SSH环境了。

4. 手动处理known_hosts与首次连接验证

配置好Sourcetree后，理论上再次进行操作（如拉取）就会触发首次连接验证。但有时图形界面的交互可能仍然不顺畅。我们可以通过一个“迂回”但绝对有效的方法来手动完成这个信任步骤：使用Git命令行手动连接一次Gitee。

这个方法的好处是，命令行的SSH会明确地提示你是否信任主机，并将密钥写入标准的 known_hosts 文件。之后，Sourcetree再连接时，就会发现密钥已缓存，从而绕过错误。

操作步骤：

1. 打开你的终端（Git Bash、CMD、PowerShell或系统终端）。
2. 输入以下命令，尝试通过SSH协议连接Gitee的Git服务器（注意，这不是克隆仓库，只是一个纯粹的SSH连接测试）：

   ssh -T git@gitee.com
   

3. 你会看到类似如下的提示信息：

   The authenticity of host 'gitee.com (xxx.xxx.xxx.xxx)' can't be established.
   ED25519 key fingerprint is SHA256:+ULzij2u99eWYFTw1W4ErYG/aepHL9527PAUCoV37.
   Are you sure you want to continue connecting (yes/no/[fingerprint])?
   

   这个指纹应该和之前在Sourcetree报错信息中看到的指纹（SHA256:+ULzij2u6666eWYFTw1W4ErYG/aepHL9527PAUCoV37）一致。仔细核对，确保你连接的是真正的Gitee服务器。
4. 确认指纹无误后，输入 yes 并回车。
5. 如果一切正常，你会看到一条欢迎信息，例如：

   Hi USERNAME! You've successfully authenticated, but GITEE.COM does not provide shell access.
   

   这表示SSH连接和认证成功。更重要的是，Gitee.com的主机密钥已经被自动添加到了你本地 ~/.ssh/known_hosts 文件中。

现在，回到Sourcetree，再次尝试拉取或推送操作。那个恼人的“主机密钥未缓存”错误应该已经消失了，操作可以顺利进行。

5. 高级排查与常见问题场景

即使按照上述步骤操作，部分开发者可能还会遇到一些“顽固”的情况。下面我们针对几个常见场景进行深度排查。

5.1 检查与修复known_hosts文件

有时 known_hosts 文件可能格式错误、包含旧条目或权限问题，导致SSH客户端无法正确读取。

• 查看known_hosts内容：你可以用文本编辑器打开 ~/.ssh/known_hosts 文件，搜索“gitee.com”。一个正常的条目看起来像这样：

  gitee.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIIw...（很长一串字符）
  

  或者可能带有端口号：

  [gitee.com]:22 ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIIw...
  

• 问题修复：
  • 格式混乱：如果文件看起来杂乱无章，你可以选择备份后删除整个文件。当你下次通过命令行 ssh -T git@gitee.com 连接时，它会自动创建一个全新的、格式正确的条目。这是一个比较彻底的方法。
  • 权限问题（主要见于Linux/macOS）：确保 .ssh 目录权限为 700，known_hosts 文件权限为 600。在终端中执行：

    chmod 700 ~/.ssh
    chmod 600 ~/.ssh/known_hosts
    

5.2 处理多个SSH密钥与配置文件

如果你为不同的平台（如Gitee、GitHub、公司GitLab）配置了多个密钥，管理它们的最佳实践是使用 ~/.ssh/config 文件。这个文件可以告诉SSH客户端，针对不同的主机使用不同的密钥。

例如，为Gitee创建一个专用配置：

Host gitee.com
    HostName gitee.com
    User git
    IdentityFile ~/.ssh/id_ed25519_gitee  # 指定用于Gitee的私钥路径
    IdentitiesOnly yes

配置好后，无论通过命令行还是Sourcetree（使用OpenSSH客户端）连接 gitee.com，都会自动使用指定的密钥。这能避免密钥选择错误带来的认证失败。

5.3 Sourcetree缓存与重启

在修改了Sourcetree的SSH配置或手动更新了 known_hosts 文件后，有时Sourcetree可能还会读取旧的缓存。一个简单的解决方法是：

1. 完全退出Sourcetree应用程序。
2. 重新启动Sourcetree。
3. 再次尝试仓库操作。

这个步骤能确保Sourcetree加载最新的配置和环境状态。

5.4 网络与防火墙的潜在影响

在极少数情况下，问题可能不在客户端配置，而在网络层面。

• 端口22阻塞：SSH默认使用22端口。确保你的公司网络或防火墙没有屏蔽对 gitee.com:22 的出站连接。你可以尝试在终端使用 telnet 或 nc 命令测试连通性：

  telnet gitee.com 22
  # 或
  nc -zv gitee.com 22
  

  如果连接失败，可能需要联系网络管理员。
• 使用HTTPS协议作为备选：如果SSH问题短期内无法解决，作为一个临时方案，你可以将远程仓库的URL从SSH格式（git@gitee.com:username/repo.git）切换为HTTPS格式（https://gitee.com/username/repo.git）。在Sourcetree中，你可以在仓库设置里修改远程URL。但请注意，HTTPS方式可能需要你频繁输入账号密码，或者配置凭据助手，在安全性和便利性上通常不如SSH。

经过以上从原理到实践，从基础配置到深度排查的梳理，你应该已经能够独立解决Sourcetree中遇到的SSH主机密钥问题。关键在于理解SSH信任链的建立过程，并确保Sourcetree使用的SSH环境与你的系统命令行环境保持一致。配置一次，以后在更换电脑或重装系统时，你也能快速复现这套稳定的Git工作流。