1. 先搞清楚 TortoiseGit 到底在跟谁借SSH很多人第一次在小乌龟上配置公私密钥卡住的地方根本不是生成密钥而是不知道密钥生成完之后该塞给谁。你在 Git Bash 里ssh-keygen敲得行云流水公钥也贴到了远端平台结果回到资源管理器右键Git Clone照样弹一个账号密码框或者干脆报Permission denied (publickey)。这时候大部分人的第一反应是我配错了实际上八成是 TortoiseGit 根本没用上你生成的那套密钥。我见过太多人反复删C:\Users\你的用户名\.ssh目录重来来回折腾两三个小时最后发现问题出在一个下拉框上。所以这篇不讲虚的从小乌龟到底调用谁这个根子上捋一遍然后给出两套能直接抄的配置路线再把多账号、权限、中文包、git.exe识别这些连带的坑一起收拾掉。适合看这篇的人Windows 上做开发、用 TortoiseGit 做图形化 Git 操作、想让git clone/git pull/git push全程免密的同学。已经会用命令行的老手也能从里面捞到几个冷门细节比如 PuTTY 格式和 OpenSSH 格式私钥互转时容易丢的东西。1.1 小乌龟不是 Git它只是个外壳这个认知必须先立住。TortoiseGit 本身不实现 Git 协议它是一层 Windows Shell 扩展加图形界面真正干活的是背后那个git.exe也就是 Git for Windows 提供的那套。你在资源管理器里看到的右键菜单、提交对话框、分支图全都是小乌龟画的皮底层调用的还是命令行 Git。这就带来一个后果TortoiseGit 的配置分两套。一套是它自己的设置Settings 里那些另一套是 Git 本身的配置.gitconfig、.ssh/config。很多人只改了其中一套另一套还是默认值于是出现命令行能推、小乌龟推不了或者反过来的精神分裂现象。SSH 这件事上小乌龟额外多插了一脚它允许你指定用哪个 SSH 客户端。这个选项就是万恶之源也是解决所有免密问题的钥匙。它藏得不深但新手基本注意不到。1.2 OpenSSH 与 PuTTY 两套人马Windows 上能用的 SSH 客户端不止一个主流的就两家OpenSSHGit for Windows 自带一份路径通常在C:\Program Files\Git\usr\bin\ssh.exeWindows 10/11 系统也自带一份独立版本在C:\Windows\System32\OpenSSH\ssh.exe。命令是ssh、ssh-keygen、ssh-add私钥是标准的 OpenSSH 格式代理叫ssh-agent。PuTTY 系TortoiseGit 安装包自带一套 PuTTY 工具包括TortoiseGitPlink.exe、puttygen.exe、pageant.exe。私钥是.ppk格式代理叫Pageant。关键点来了这两套的私钥格式不通用代理也不通用。你用ssh-keygen生成的id_ed25519Pageant不认你用puttygen生成的.ppkssh.exe也不认。如果你在 TortoiseGit 里指定了TortoiseGitPlink.exe作为 SSH 客户端但密钥是 OpenSSH 格式、代理跑的是ssh-agent那必然握手失败而且报错信息往往很含糊只说一句PuTTY Fatal Error: Disconnected: No supported authentication methods available。所以配置的第一步不是敲命令而是先选边站。选 OpenSSH 就一路 OpenSSH选 PuTTY 就一路 PuTTY千万别混着来。1.3 两条路线的对照表我把两条路线摊开对比一下你按自己的习惯挑别纠结哪个更高级对比项OpenSSH 路线PuTTY 路线SSH 客户端C:\Program Files\Git\usr\bin\ssh.exeTortoiseGit 自带TortoiseGitPlink.exe生成工具ssh-keygenputtygen.exe私钥格式id_ed25519无扩展名xxx.ppk密钥代理ssh-agentWindows 服务pageant.exe托盘程序配置文件~/.ssh/configPlink 会话 / 注册表已知主机记录~/.ssh/known_hosts注册表HKCU\Software\SimonTatham\PuTTY\SshHostKeys与 Git Bash 共用天然共用需要转换密钥多账号支持config 文件里写 Host 别名干净需要存多个 Session略啰嗦我的建议很直接如果你平时也会开 Git Bash 敲命令就统一走 OpenSSH 路线。理由是小乌龟只是你的可视化入口命令行才是兜底手段两边共用一套密钥和 config出问题时排查面小一半。如果你从来不开命令行、纯图形化操作那走 PuTTY 路线也完全没问题毕竟那是小乌龟的原生搭档。提示不要因为小乌龟自带 Plink就默认走 PuTTY。默认值不等于最优解先把路线定了再动手生成密钥。2. 生成密钥对ssh-keygen 与 PuTTYgen 各写一遍标题里说的公私秘钥标准叫法是密钥对私钥自己留着公钥贴到远端平台。私钥等价于你的身份凭证泄了就等于别人能冒充你往仓库里推代码。所以下面每一步都会说清楚为什么这么干而不是只丢命令。2.1 先决定密钥类型ed25519 还是 RSA2024 年之后新建密钥我的默认答案是ed25519。它密钥短、签名快、安全性对等生成的公钥只有一行贴起来干净。RSA 唯一的优势是兼容性——极少数老旧平台或内部系统可能还不支持 ed25519那就退回到 RSA 4096 位。一个常见误区是位数越高越安全。RSA 2048 到今天依然没被实际攻破4096 更多是心理安慰而 ed25519 用 256 位就达到甚至超过 RSA 3072 的安全强度靠的是椭圆曲线数学。别盲目追求 8192 位那个生成慢不说某些服务端还会拒收。要不要给密钥加口令passphrase加了更安全代价是每次用都得解锁一次所以必须配合代理ssh-agent或Pageant才能做到解锁一次、管一整个会话。如果你打算配代理就加口令如果你懒得配代理那宁可不加因为无口令密钥文件本身就是凭证加了口令又不配代理等于自找麻烦。2.2 用 OpenSSH 路线生成含代理配置打开 Git Bash或者 PowerShell 里带上全路径执行ssh-keygen -t ed25519 -C your_emailexample.com -f ~/.ssh/id_ed25519_work几个参数说清楚-t ed25519指定算法。老平台不支持就换成-t rsa -b 4096。-C注释通常写邮箱。它只是给公钥末尾加个标记方便你在平台上一堆公钥里认出哪把是哪把不参与加密。-f指定输出路径。省略的话默认是~/.ssh/id_ed25519。多账号场景强烈建议起个有意义的名字比如id_ed25519_work、id_ed25519_gitee比默认名好认得多。执行后会问两遍口令直接回车就是空口令。生成完~/.ssh/下会多出两个文件私钥无扩展名和公钥.pub结尾。私钥那个文件千万别发给任何人包括你以为的运维同学。验证一下指纹确认生成成功ssh-keygen -lf ~/.ssh/id_ed25519_work.pub输出类似256 SHA256:xxxxxxxx... your_emailexample.com (ED25519)。这个SHA256:后面的串就是指纹待会儿在远端平台比对用。2.3 用 PuTTY 路线生成 .ppk如果你选了 PuTTY 路线找到puttygen.exe开始菜单里搜 PuTTYgen或者在 TortoiseGit 安装目录bin下。启动后底部Parameters区选EdDSA对应 ed25519或RSARSA 的话把位数拨到 4096。点Generate然后在空白区域不停晃鼠标——这不是玄学PuTTYgen 靠鼠标移动采集熵值来喂随机数生成器晃动越乱生成越快。Key comment填个能认出来的标记比如work-laptop-2024。Key passphrase填口令不填也行见前面的建议。先点Save private key存成.ppk比如D:\keys\work.ppk。再点Save public key存一份公钥或者直接把上面那个大文本框的内容复制走。这里有个特别容易踩的坑PuTTYgen 上面那个文本框里的公钥格式和 OpenSSH 格式不一样。它是一段被换行打乱的 Base64虽然多数平台能接受但有些平台尤其是同时校验格式的会报公钥格式不合法。稳妥做法是粘贴前先确认平台要求的格式OpenSSH 格式应该是ssh-ed25519 AAAA... comment单行形式。2.4 两种格式私钥的互转以及转换时丢的东西现实情况是你往往两套工具都在用。这时候需要转换PuTTYgen 打开 OpenSSH 私钥菜单Conversions→Import key选中你的id_ed25519然后Save private key存成.ppk。注意如果原密钥有口令导入时要输入。OpenSSH 私钥导出在 PuTTYgen 里导入.ppk后菜单Conversions→Export OpenSSH key。它会提醒你这样导出的私钥不带口令保护是否继续。这个提醒不是吓唬人。OpenSSH 的私钥加密格式和 PuTTY 的.ppk加密格式是两套东西导出时只能导成明文再靠 OpenSSH 自己保护。所以转换完的私钥文件要么立刻配好权限要么马上用ssh-keygen -p -f 私钥文件重新加口令。我见过有人转换完把明文私钥放桌面放了一星期这个习惯非常危险。注意转换会改变文件格式但不会改变密钥本身。也就是说同一对密钥的 OpenSSH 版本和.ppk版本公钥指纹是一致的远端平台不需要重新贴。这点可以用来验证转换有没有出错。3. 把公钥挂到远端平台以及顺手要做对的几件小事密钥生成完只是半成品公钥没挂上去之前服务器根本不知道你是谁。这一步看着简单但细节不少尤其是多平台多账号的场景。3.1 公钥往哪贴怎么贴主流平台的位置大同小异登录后进个人设置找 SSH 密钥SSH Keys / 公钥管理点新增把xxx.pub文件的全部内容粘进去。这里强调三件事第一粘的是公钥不是私钥。判断方法很简单公钥以ssh-ed25519或ssh-rsa开头全文只有一行私钥是一大坨以-----BEGIN OPENSSH PRIVATE KEY-----开头、多行的内容。后者粘上去平台顶多提示你格式不对更糟的是有些平台不校验直接存了等于你把家门钥匙挂在公告栏上。第二结尾的注释可以删。ssh-ed25519 AAAA... youremail.com里的邮箱只是备注删掉不影响使用但留着方便日后识别。平台一般会把注释显示为密钥名称。第三别用文本编辑器复制导致自动换行。有些编辑器会在显示时软换行复制出来却把换行符带进去了粘到平台就报格式错误。建议用type命令或者记事本查看确保复制的是完整单行。3.2 指纹格式不一样别自己吓自己同一个密钥在不同工具里显示的指纹格式不同这是新手最容易怀疑我是不是配错了的地方ssh-keygen -lf输出的是SHA256:xxxx...形式Base64 编码。PuTTYgen 默认显示的是SHA256指纹但也可能显示旧的 MD5 形式xx:xx:xx:...。远端平台展示的通常是SHA256:xxxx...。比对的时候只看SHA256:后面那段忽略等号结尾的填充和前后空格。如果平台展示的是 MD5 冒号分隔格式可以点它旁边的切换按钮换成 SHA256或者在本机用ssh-keygen -E md5 -lf 公钥文件生成 MD5 指纹来对。比对指纹的价值在于确认我贴上去的确实是这把密钥。如果你机器上有多把同名密钥、或者刚做过格式转换这一步能帮你排除掉大部分玄学问题。3.3 多账号多密钥config 文件比什么都好使一个人同时用公司账号、个人账号密码学上最佳实践是一个身份一把密钥而不是一把密钥到处用。这样万一某把泄露撤销一把就行不影响其他。问题来了多把密钥SSH 怎么知道连某个域名时该用哪把答案是~/.ssh/config文件OpenSSH 路线。举个实际能用的例子# 个人主账号 Host github.com HostName github.com User git IdentityFile ~/.ssh/id_ed25519_personal IdentitiesOnly yes # 公司账号假设平台支持独立域名或端口区分 Host git.company.com HostName git.company.com User git IdentityFile ~/.ssh/id_ed25519_work IdentitiesOnly yes几个字段解释一下Host你自己起的别名ssh命令里写这个就匹配到这一段。HostName真实域名。UserSSH 登录用户名。代码托管平台基本都是git别写成你的账号名这是高频错误。IdentityFile指明用哪把私钥。IdentitiesOnly yes这个字段最容易被忽略但极其重要。不加它SSH 会先把代理里所有密钥挨个试一遍很多平台限制认证尝试次数比如 6 次试到一半就被踢报Too many authentication failures。加上它就只试指定的这一把。如果你发现某个平台必须用同一域名但不同账号比如两个 Gitee 账号那就得靠 Host 别名加改写远程地址Host gitee-work HostName gitee.com User git IdentityFile ~/.ssh/id_ed25519_work_gitee然后远程地址写成gitgitee-work:用户名/仓库.gitSSH 会把gitee-work解析成gitee.com。这个技巧在克隆时特别有用不用改全局配置。3.4 私钥别进仓库这条每年都有人犯。项目里建了个keys目录放部署密钥顺手git add .提交上去了公钥私钥一起进了版本历史。就算后面删掉历史里还在git log一翻就出来。防呆手段有三个把密钥目录放在仓库外在.gitignore里显式写*.pem、*.ppk、id_*用提交前检查。真提交错了光删文件没用得用git filter-repo之类工具重写历史然后第一时间到平台撤销那把密钥因为一旦推上去就该假设它已经泄露了。4. TortoiseGit 里最关键的一步把 SSH client 指到对的 exe前面全是对的准备这一节才是标题里小乌龟三个字的落点。90% 的配了密钥但还是弹密码框问题答案都在这里。4.1 设置入口的准确路径在任意文件夹空白处右键 →TortoiseGit→Settings。左侧树找Network右边就是 SSH client 那一栏一个输入框加一个Browse按钮。有的版本汉化后写的是网络和SSH 客户端。输入框的默认值通常是C:\Program Files\TortoiseGit\bin\TortoiseGitPlink.exe老版本可能是TortoisePlink.exe。你所有 SSH 相关的疑难杂症都先从这里看起。提示改完设置后已经打开的对话框不会自动生效要关掉重开。我见过有人改完设置直接在原来那个报错的窗口点重试当然还是失败然后怀疑设置没保存。4.2 三种情况分别怎么填根据你的路线和实际环境分三种填法你的情况SSH client 填写内容配套要求走 OpenSSH 路线用 Git 自带的C:\Program Files\Git\usr\bin\ssh.exe密钥在~/.sshssh-agent按需启动走 OpenSSH 路线用系统自带C:\Windows\System32\OpenSSH\ssh.exe同上走 PuTTY 路线C:\Program Files\TortoiseGit\bin\TortoiseGitPlink.exe密钥是.ppkPageant 加载该.ppk选ssh.exe的好处是和小乌龟外的命令行环境完全一致~/.ssh/config里的多账号配置直接生效。选TortoiseGitPlink.exe的好处是首次连接时的主机密钥确认弹窗更友好而且和 Pageant 集成顺滑。一个必须知道的细节TortoiseGitPlink.exe不读~/.ssh/config它读的是 PuTTY 的会话Session和注册表。这意味着你在 config 里写的多账号配置切到 Plink 后全部失效。这也是我建议统一走 OpenSSH 的核心理由之一。4.3 首次连接的 known_hosts 与弹窗不管你选哪套第一次连某个服务器都会弹一个确认框问你信不信这个主机。这是 SSH 的防中间人机制服务器把自己的主机公钥给你你确认后本机记住它下次再连就不问了。OpenSSH 路线记录写到C:\Users\你的用户名\.ssh\known_hosts。PuTTY 路线记录写到注册表HKEY_CURRENT_USER\Software\SimonTatham\PuTTY\SshHostKeys。如果服务器换过主机密钥比如平台迁移你会看到刺眼的警告提示主机密钥变了。这时候别条件反射点Yes先去平台官网核对新指纹确认无误再删掉旧记录重连。直接点 Yes 等于放弃这层保护。4.4 顺手解决中文包不生效和 git.exe 识别不到这两个是搜索热词里出现频率极高的和 SSH 配置属于同一片雷区一起说了。中文包不生效TortoiseGit 的语言包是独立安装的而且必须和主程序版本号严格对应32 位装 32 位、64 位装 64 位。装完还不生效检查两处一是Settings→General→Language有没有选中文选完要重启资源管理器才刷新菜单二是主程序版本和语言包版本对比差一个小版本就可能不识别。最干脆的办法是卸掉主程序重装最新版再装完全同版本的语言包。configure git.exe 无法识别到 git.exe path这个报错说明 TortoiseGit 找不到git.exe。去Settings→General→Git.exe Path指到C:\Program Files\Git\bin\git.exe。注意两点要的是git.exe不是git-bash.exe也不是git-cmd.exebin\git.exe和cmd\git.exe都能用但两者行为略有差异一般选bin下的。如果你根本没装 Git for Windows光装小乌龟是不够的——小乌龟不含git.exe必须先装 Git 本体。另外一个常见现象是命令行里敲git提示无法将 git 项识别为 cmdlet、函数、脚本文件或可运行程序的名称这是 Windows 环境变量Path里没加C:\Program Files\Git\bin。加完 Path 一定要重开终端旧窗口不会刷新环境变量这坑我也踩过。5. 验证与排错从没反应到一键免密配置完别急着开项目按下面的顺序分层验证出问题才能定位到具体环节而不是笼统地用不了。5.1 分层验证思路我习惯分四层从底往上密钥文件层ssh-keygen -lf 公钥文件能不能输出指纹能说明文件是好的。网络与握手层ssh -T git域名能不能连上OpenSSH 路线在 Git Bash 里敲ssh -T gitgitee.com成功会返回一句欢迎语类似Hi 用户名! Youve successfully authenticated...。注意这里返回非零退出码是正常的平台只提供 shell 访问不给你登录会话所以别看到退出码就以为失败。Git 层git ls-remote git域名:用户名/仓库.git能列出引用吗这一步绕过了小乌龟验证 Git 本身能通过 SSH 拿到仓库数据。小乌龟层右键Git Clone或Pull看还弹不弹密码框。哪一层断了就只排查那一层。比如前两层都过第三层报权限不够那多半是仓库地址写错或账号对该仓库没权限如果前三层都过只有小乌龟失败那必然是SSH client那个输入框指错了。5.2 常见报错对照表报错关键词大概率原因处理方向Permission denied (publickey)服务器没收到有效公钥检查公钥是否贴上、IdentityFile是否指对No supported authentication methods availablePlink 用了 OpenSSH 格式私钥或反之统一路线做格式转换Too many authentication failures代理里密钥太多逐个试超限config 里加IdentitiesOnly yesHost key verification failed主机密钥变了或 known_hosts 冲突核对平台官方指纹后再更新记录UNPROTECTED PRIVATE KEY FILE私钥文件权限对他人开放用icacls收紧权限见下节反复弹账号密码框远程地址还是 HTTPSgit remote set-url换成 SSH 地址Could not resolve hostname域名拼错或 hosts 被改核对域名拼写这张表建议收藏遇到报错先搜关键词比漫无目的地重装快得多。5.3 Windows 上私钥权限被拒的处理OpenSSH 会检查私钥文件是不是只有你能读。这个检查在 Linux 上看chmod在 Windows 上看的是 ACL访问控制列表。Git Bash 里的chmod 600在 Win32 环境下往往不起作用得用icaclsicacls C:\Users\你的用户名\.ssh\id_ed25519_work /inheritance:r icacls C:\Users\你的用户名\.ssh\id_ed25519_work /grant:r %USERNAME%:R第一句断开继承第二句只给你自己读权限。执行完再ssh -T试一次。这个坑的典型特征是Git Bash 里一切正常但换个终端或换用户就报UNPROTECTED PRIVATE KEY FILE因为 ACL 继承自父目录把权限放开了。注意/grant:r里的:R是只读权限。如果写成:F完全控制虽然也能用但权限给太宽不如只读干净。改完用icacls 文件路径查看确认。5.4 代理开机自启免密才算闭环密钥配好之后如果每次重启电脑都要重新输一次口令那免密只完成了一半。两种代理的自启方式OpenSSH 路线Windows 自带ssh-agent服务默认是禁用或手动的需要改成自动启动。# 以管理员身份打开 PowerShell Set-Service -Name ssh-agent -StartupType Automatic Start-Service ssh-agent # 然后加载私钥每台机器只需做一次之后会持久化 ssh-add C:\Users\你的用户名\.ssh\id_ed25519_work注意Git for Windows 自带的ssh.exe和 Windows 系统自带的ssh.exe用的是不同的 agent。如果你在小乌龟里填的是 Git 自带的ssh.exe但私钥加到了系统的 agent 里可能还是不通。最省事的做法是统一用一家的 exe我一般统一用 Git 自带的。PuTTY 路线把pageant.exe的快捷方式丢进启动目录shell:startup开机自动跑然后右键托盘图标Add Key加载.ppk。Pageant 的好处是加载密钥后任何用 Plink 的程序都能共享包括小乌龟的提交对话框。5.5 几个容易忽略的小习惯最后分享几个我在长期使用中养成的习惯能省下不少返工时间。第一密钥按用途命名并记录指纹。在密码管理器或者一份加密文档里记下哪把密钥对应哪个平台、什么时候生成的、指纹是多少。密钥用久了尤其是换了电脑之后光看文件名根本想不起来哪把是哪把。第二换电脑时用导出导入别重新生成。直接在平台上删旧公钥、传新公钥虽然也能用但如果你有服务器上配了authorized_keys、CI 里配了部署密钥全都得跟着改。养成备份密钥文件的习惯迁移时省事得多。第三定期清理远端平台上不用的公钥。实习生离职、旧笔记本报废对应的公钥留在平台上就是个隐患。建议每半年过一遍密钥列表把半年没用的删掉。第四别用git commit --amend提交密钥相关的修复。有人发现自己不小心提交了密钥改完后--amend一下想掩盖痕迹但--amend只改最近一次提交之前的历史里还留着而且如果已经推过远端还留有旧对象。正确做法是先撤销密钥再处理历史。第五切换分支和配密钥是两件独立的事。搜索热词里tortoisegit 切换分支和密钥配置经常一起出现但切换分支走的是本地仓库操作和 SSH 认证无关。如果你切换分支后推送失败先确认远程地址是不是 SSH而不是去动密钥配置。我个人在实际操作中的体会是这套东西最大的成本不在技术本身而在信息不对称——不知道小乌龟背后还藏着一个 SSH client 选项不知道 Plink 和 OpenSSH 是两套体系于是把所有问题都归因到密钥没配好然后一遍遍删了重来。把这两层关系理清楚后面所有操作都是顺水推舟。遇到问题不要慌着重装先分层验证一遍答案通常就在那张报错表里。