SSH Key 配置排错解决 SourceTree 克隆 SSH 仓库转圈的 3 种场景当你在 Mac 上配置好 SSH Key 后满怀期待地打开 SourceTree 准备克隆 GitHub 仓库却发现进度条一直转圈这种体验确实令人沮丧。本文将带你深入排查三种常见场景下的 SSH 连接问题让你快速恢复高效的开发流程。1. 诊断 SSH 连接问题的分步检查清单在开始具体场景的排查前我们先建立一个系统性的检查流程。打开终端按顺序执行以下命令# 1. 检查 SSH 密钥是否存在 ls -al ~/.ssh/id_*.pub # 2. 测试基础连接性 ssh -T gitgithub.com # 3. 验证 SSH 代理状态 ssh-add -l如果第一步没有显示任何文件说明你的 SSH 密钥可能没有正确生成。这时需要重新创建密钥ssh-keygen -t ed25519 -C your_emailexample.com提示Ed25519 算法比传统的 RSA 更安全高效。如果系统不支持可以使用ssh-keygen -t rsa -b 4096替代。第二步命令应该返回类似以下的成功消息Hi username! Youve successfully authenticated...如果看到Permission denied错误说明认证失败。第三步检查 ssh-agent 是否加载了你的密钥。如果列表为空需要手动添加ssh-add ~/.ssh/id_ed255192. 场景一仓库非公开导致的认证失败现象SourceTree 克隆私有仓库时转圈但公开仓库正常。根因分析GitHub 对公开和私有仓库的权限检查机制不同。即使 SSH 配置正确如果没有仓库的读取权限连接会卡在认证阶段。解决方案确认仓库的可见性设置访问 GitHub 仓库页面检查Settings → General中的仓库可见性检查你的 GitHub 账号是否有该仓库的访问权限如果是组织仓库确保你已被添加到成员列表如果是私有仓库确认所有者已邀请你为协作者临时测试尝试克隆一个公开仓库如gitgithub.com:github/docs.git验证 SSH 基础功能深度排查使用-v参数查看详细连接日志ssh -vT gitgithub.com在输出中查找关键行debug1: Offering public key: ~/.ssh/id_ed25519 ED25519 SHA256:xxxx debug1: Server accepts key: ~/.ssh/id_ed25519 ED25519 SHA256:xxxx如果看到Access denied说明密钥已正确识别但权限不足。3. 场景二~/.ssh/config 配置缺失现象终端可以正常连接但 SourceTree 持续转圈。根因分析SourceTree 使用的 SSH 环境可能与终端不同缺少必要的配置参数。解决方案创建或编辑配置文件nano ~/.ssh/config添加以下内容根据你的密钥路径调整Host github.com HostName github.com User git IdentityFile ~/.ssh/id_ed25519 AddKeysToAgent yes UseKeychain yes设置正确的文件权限chmod 600 ~/.ssh/config配置参数详解参数作用必要性IdentityFile指定密钥路径必需AddKeysToAgent自动加载密钥到代理推荐UseKeychain在钥匙串存储密码macOS 特有注意如果使用 RSA 密钥确保配置文件的 IdentityFile 指向正确的私钥路径如~/.ssh/id_rsa。4. 场景三ssh-agent 未正确启动现象首次克隆成功但重启后 SourceTree 又出现转圈。根因分析ssh-agent 是临时进程默认不会在系统重启后保持密钥加载状态。解决方案方法一手动加载密钥确保 ssh-agent 正在运行eval $(ssh-agent -s)添加密钥到代理ssh-add --apple-use-keychain ~/.ssh/id_ed25519方法二自动化配置推荐编辑你的 shell 配置文件如 ~/.zshrc 或 ~/.bashrcnano ~/.zshrc添加以下内容# 自动启动 ssh-agent if [ -z $SSH_AUTH_SOCK ]; then eval $(ssh-agent -s) ssh-add --apple-use-keychain ~/.ssh/id_ed25519 fi使配置立即生效source ~/.zshrc验证代理状态ssh-add -l正常输出应显示加载的密钥指纹256 SHA256:xxxxxxxxxxxx your_emailexample.com (ED25519)5. 高级排查网络与代理设置如果上述方案均无效可能需要检查网络环境测试 SSH 端口连通性nc -zv github.com 22检查 Git 远程配置git config --global -l | grep ssh临时关闭防火墙测试sudo /usr/libexec/ApplicationFirewall/socketfilterfw --setglobalstate off警告测试后记得重新启用防火墙sudo /usr/libexec/ApplicationFirewall/socketfilterfw --setglobalstate on对于企业网络环境可能需要配置代理# 设置 Git 使用代理 git config --global http.proxy http://proxy.example.com:8080 git config --global https.proxy https://proxy.example.com:80806. 终极验证SSH 连接全流程测试为确保所有环节正常工作建议执行以下完整测试序列生成新的测试密钥避免影响现有配置ssh-keygen -t ed25519 -f ~/.ssh/test_key -C testexample.com将公钥添加到 GitHub 测试账号pbcopy ~/.ssh/test_key.pub测试克隆操作GIT_SSH_COMMANDssh -i ~/.ssh/test_key git clone gitgithub.com:username/testrepo.git检查 SourceTree 设置打开 Preferences → Git确认SSH Client选择的是OpenSSH检查SSH Key指向正确的私钥文件通过这种隔离测试可以精准定位是密钥问题、配置问题还是环境问题。