SourceTree提示SSH密钥无效怎么办 SourceTree配置方法【指南】

SourceTree SSH密钥失效时，需先执行eval "$(ssh-agent -s)"和ssh-add ~/.ssh/gitee加载密钥，Mac用户必须加-K参数存入钥匙串并配置~/.ssh/config启用UseKeychain yes和AddKeysToAgent yes，Windows用户须在SourceTree设置中切换为系统OpenSSH客户端并重启程序，最后通过ssh -T git@gitee.com验证成功后方可正常使用克隆、推送与拉取功能。

SourceTree提示SSH密钥无效时，克隆、推送、拉取全部卡在认证环节，根本连不上Gitee或GitHub服务器——这不是仓库地址写错了，而是你的私钥没被正确加载、没被SourceTree识别，或者系统SSH代理压根没启动。

确认SSH密钥是否真的生效

打开终端（Mac/Linux）或Git Bash（Windows），执行：
ssh -T git@gitee.com

如果返回 【Hi xxx! You've successfully authenticated】，说明密钥本身没问题，问题出在SourceTree调用链上；如果提示 【Permission denied (publickey)】 或 【Could not open a connection to your authentication agent】，说明密钥未加载或代理未运行，必须先解决这一步再进SourceTree设置。

遇到“agent not running”错误，立即执行：
eval "$(ssh-agent -s)" → ssh-add ~/.ssh/gitee

SourceTree中强制切换为系统OpenSSH客户端

这是Windows用户90%失效问题的根源：SourceTree默认捆绑PuTTY/Plink，但你的密钥是OpenSSH格式（id_rsa或gitee），Plink根本读不懂。

方法一（推荐）：
【工具】→【选项】→【一般】→ 找到“SSH Client Configuration”→ 将下拉菜单从“PuTTY/Plink”改为【OpenSSH】 → 点击确定。

方法二（备用）：
如果改完仍报错，点击同一页面右下角的【浏览】按钮，手动定位到系统OpenSSH路径：
Windows 10/11：C:\Windows\System32\OpenSSH\ssh.exe
Mac：/usr/bin/ssh

注意：改完必须重启SourceTree，否则新配置不生效。

让密钥永久驻留钥匙串（Mac专属关键步骤）

Mac用户重启后SSH密钥频繁掉线，不是密钥坏了，而是没存进钥匙串。仅用ssh-add添加是会话级的，关终端就丢。

第一步：确保已生成密钥并位于~/.ssh/gitee
第二步：执行 ssh-add -K ~/.ssh/gitee
第三步：编辑 ~/.ssh/config 文件，加入以下三行：

Host gitee.com
 UseKeychain yes
 AddKeysToAgent yes

第四步：删掉旧的known_hosts条目（避免指纹冲突）：
ssh-keygen -R gitee.com

这四步做完，重启终端再跑 ssh -T git@gitee.com，提示成功后，SourceTree就能稳定连接了。

检查并修复known_hosts缓存缺失

SourceTree弹出“The host key is not cached”却无确认框，是因为它无法触发交互式信任流程。

① 先在终端里手动完成首次信任：
ssh -o StrictHostKeyChecking=no git@gitee.com

② 这会自动把gitee.com的主机公钥写入 ~/.ssh/known_hosts
③ 回到SourceTree，直接尝试克隆或推送，不再卡住

如果已存在known_hosts但内容混乱，可安全删除该文件，再执行①重新生成——【删除前不用备份，重连时会自动生成】。

验证SourceTree是否真正在用你的私钥

打开SourceTree → 【仓库】→ 【仓库设置】→ 【远程】→ 查看URL是否为git@gitee.com:xxx/xxx.git格式（必须是git@开头，不是https://）

然后点【高级】→ 检查“SSH Key”字段：
• 如果显示“Not set”，说明SourceTree没找到密钥，需回到上一步确认OpenSSH路径和config文件；
• 如果显示路径如C:\Users\Name\.ssh\gitee，说明已识别，此时问题一定在系统层（agent未加载或权限拒绝）。

Windows用户特别注意：.ssh文件夹和密钥文件的NTFS权限必须允许当前用户“读取”，否则SourceTree进程直接被拒。