很多人在Win11上折腾Git连Gitee第一反应就是去网上搜git配置gitee密钥结果搜出来的教程要么年代久远要么步骤残缺照着做完还是报Permission denied (publickey)。这篇文章我把从零到能正常git clone和git push的完整链路写清楚包括SSH Key的生成原理、配置到Gitee的具体位置、Win11下容易被忽略的系统设置以及我踩过的坑和排查思路。内容覆盖从Git安装到最后多仓库共存不管你是刚接触Git的新手还是被SSH问题卡住的老手顺着往下走基本都能解决。1. 动手前的环境准备与Win11几个坑1.1 为什么Win11下配SSH Key值得单独写一篇先说个现象很多人在Win10上配SSH Key很顺利换到Win11就各种不顺。这不是玄学是Win11确实改动了一些底层设置。比如右键菜单默认收起、自带终端从cmd换成了Windows Terminal、OpenSSH客户端变成了可选功能甚至首次连Gitee时会弹防火墙授权处理不好直接超时。另外Win11对用户目录权限管得更严如果你把密钥文件放在C:\Users\你的用户名\.ssh下不注意权限设置SSH客户端就会直接拒绝使用这个密钥。这一篇就围绕Win11环境来讲把每一步能遇到的问题都提前说明白省得你去翻十几个帖子拼答案。1.2 Git在Win11的安装与初始配置Gitee本身是基于Git的代码托管平台所以第一步肯定是把Git装好。去Git官网下载Windows版本安装包一路Next就能装完。有几个选项需要注意安装路径建议保持默认如果改了注意路径里不要出现中文和空格。在选择默认编辑器那一步如果你不熟悉Vim建议选Notepad或者VS Code方便后面提交代码时编辑提交信息。在调整PATH环境变量那一步选默认的“Git from the command line and also from 3rd-party software”就行。换行符转换那一步选默认的“Checkout Windows-style, commit Unix-style line endings”这是Windows下最省心的方案。安装完验证一下是否成功打开任意终端窗口Win11推荐在文件夹地址栏输入cmd或者直接在开始菜单搜索“终端”输入git --version能正常输出版本号比如git version 2.40.0.windows.1就说明安装成功。紧接着设置全局用户信息这是Git提交时必须携带的信息不设置的话提交时会报错git config --global user.name 你的名字 git config --global user.email 你的邮箱这里有个细节user.name和user.email会写进每一次commit里Gitee也会根据邮箱匹配到你的账号。所以邮箱最好填Gitee注册时用的邮箱这样提交记录能正确关联到你的Gitee头像。1.3 Win11下终端和右键菜单的几个小坑Win11和Win10在终端使用上最明显的区别就是右键菜单。Win11默认右键是精简菜单里面没有“Git Bash Here”和“在终端中打开”。你需要在右键菜单底部找到“显示更多选项”才能看到传统的完整菜单。这一步有几种解决办法安装Git时勾选“Windows Explorer integration”会在右键菜单的“更多选项”里加入“Git Bash Here”和“Git GUI Here”。用Win11自带终端在文件夹空白处按Ctrl Shift 右键会直接在当前目录打开Windows Terminal。也可以在文件夹地址栏输入powershell回车直接在该路径打开PowerShell窗口。另外Win11默认把终端从cmd换成了Windows Terminal如果你初次打开看到的界面和网上老教程不一样不用慌功能是兼容的。后面所有命令在cmd、PowerShell、Windows Terminal、Git Bash里都能跑只是个别命令的语法略有差异我会在文里标注。还有一个容易被忽略的点Win11的OpenSSH客户端默认可能没被启用。检查方式是打开“设置 → 系统 → 可选功能”看看“OpenSSH 客户端”是否已安装。如果没装点击“添加可选功能”搜索并安装。这个组件缺失会导致你输入ssh命令时提示“无法识别”。2. SSH Key生成与Gitee配置全流程2.1 生成SSH Key到底在做什么很多人照着教程敲完ssh-keygen就复制粘贴但不知道这一堆操作到底在干什么。简单说SSH Key是一对非对称加密密钥一个是私钥留在你电脑里绝不外传一个是公钥可以放心地贴到Gitee后台。Gitee通过公钥来识别“你用这台电脑访问是合法的”而私钥用来证明“你确实是持有该公钥的人”。Git支持的密钥算法有好几种常见的有RSA和ED25519。RSA是老牌算法兼容性最好但4096位的密钥比较长生成和验证都慢一些。ED25519是近几年流行的算法密钥短、速度快、安全性也足够Git 2.31以后和Gitee都支持。我个人的建议是优先用ED25519除非你手上有老系统或老客户端的兼容性要求。生成密钥的命令如下建议至少加上-C注释参数方便以后区分这个密钥是哪台电脑、干什么用的ssh-keygen -t ed25519 -C your_emailexample.com想用RSA的话ssh-keygen -t rsa -b 4096 -C your_emailexample.com执行后会有几步交互第一次提示Enter file in which to save the key让你选择密钥文件保存位置。一般默认C:\Users\你的用户名\.ssh\id_ed25519直接回车即可。第二次提示Enter passphrase这是给私钥加一层密码保护。建议设一个即使私钥泄露别人没有这个密码也使用不了。当然如果你觉得每次操作都要输密码太烦可以留空但安全性会打折。第三次确认密码。完成后在.ssh目录下会生成两个文件私钥无后缀和公钥.pub后缀。.pub文件是你需要给Gitee的。2.2 私钥放哪、公钥贴哪——两个关键位置私钥的位置刚才说了默认在C:\Users\你的用户名\.ssh\下。这里有个Win11容易踩的坑.ssh目录的权限。如果私钥文件的权限设置得过于宽松比如其他用户也能读取OpenSSH客户端会直接拒绝使用该密钥报UNPROTECTED PRIVATE KEY FILE之类的错误。解决办法是在文件属性里收紧权限右键私钥文件 → 属性 → 安全 → 高级 → 禁用继承 → 将继承的权限转换为显式权限 → 然后只保留当前用户删除其他用户条目。如果嫌图形界面麻烦也可以用命令快速设置在PowerShell或终端里执行icacls $env:USERPROFILE\.ssh\id_ed25519 /inheritance:r /grant:r $env:USERNAME:F再说公钥要贴到哪里。登录Gitee网页端进入“头像 → 设置 → 安全设置 → SSH公钥”。把.pub文件内容复制进去。公钥内容通常以ssh-ed25519 AAAA...或ssh-rsa AAAA...开头粘贴时不要漏掉最后的邮箱注释也不要加多余空格。Gitee每个账号可以添加多个公钥也就是说你可以把家里电脑、公司电脑、笔记本的公钥都加进去用哪个都行。公钥本身不敏感泄露了也不会让人直接登录你的Gitee账号但为了安全还是不建议随处粘贴。2.3 验证配置是否成功配置完公钥别急着克隆仓库先验证一下能否连接上Gitee的SSH服务。在终端里执行ssh -T gitgitee.com首次连接会提示确认服务器指纹The authenticity of host gitee.com (IP地址) cant be established. ED25519 key fingerprint is SHA256:xxx. Are you sure you want to continue connecting (yes/no)?输入yes回车即可这个指纹信息会记入known_hosts文件下次不再询问。之后如果看到类似于Hi 用户名! Youve successfully authenticated, but GITEE.COM does not provide shell access.的内容就说明SSH Key配置成功了。如果这里报错别急着往下走先根据错误信息排查。最常见的Permission denied (publickey)就是Gitee没有匹配到你的公钥或者私钥路径没有正确识别。我会在第5节详细讲排查方法。3. Win11下克隆与拉取Gitee仓库的实战步骤3.1 从HTTPS切换到SSH两种仓库地址的选择Gitee上的每个仓库都有两种远程地址HTTPS和SSH。HTTPS地址形如https://gitee.com/用户名/仓库名.gitSSH地址形如gitgitee.com:用户名/仓库名.git。很多教程默认让你用HTTPS克隆因为不需要配置任何东西。但HTTPS有两个痛点一是推送代码时需要反复输入Gitee的用户名密码虽然Win11自带凭据管理器可以记住但首次还是要输二是如果你开了两步验证HTTPS方式还会因为密码校验问题反复被拒。SSH的优势就是配置一次之后推送拉取都不用输密码。如果你之前已经用HTTPS克隆过仓库想改成SSH在仓库目录下执行git remote set-url origin gitgitee.com:用户名/仓库名.git然后git remote -v确认一下地址是否切换成功。3.2 完整实操克隆、修改、提交、推送现在从头走一遍流程。假设Gitee上已经有一个仓库叫my-project我在本机把它克隆下来git clone gitgitee.com:用户名/my-project.git这一步会使用你第2节配置的SSH Key来做认证。如果本地路径下没有私钥文件或者Gitee上没有对应的公钥都会在这里报错。克隆完成以后进入项目目录正常开发。改完代码以后标准的提交推送流程是git add . git commit -m 提交说明 git push这里的git push默认推送到origin远程仓库的当前分支。如果你刚初始化仓库可能会有两步提示首次推送需要指定上游分支执行git push -u origin master或git push -u origin main即可。之后就能直接git push了。拉取远程更新的代码用git pullgit pull相当于git fetch加git merge把远程最新的提交拉下来并合并到本地。如果本地有未提交的修改可能会产生冲突或要求你先stash这种情况我会在第5节展开说。3.3 让ssh-agent记住密码Win11下开机自动启动如果你在生成密钥时设置了passphrase私钥密码那么每次用SSH操作Git时都会要求输入这个密码。这很安全但也很烦。解决办法是用ssh-agent把这个密码记住。ssh-agent是OpenSSH自带的一个后台程序专门用来保存已解锁的私钥。在Windows上它是作为一个Windows服务存在的服务名叫“OpenSSH Authentication Agent”。默认情况下这个服务可能是停止且禁用状态的需要手动启用。启用方式有两种第一种图形界面。按Win R输入services.msc回车找到“OpenSSH Authentication Agent”双击把启动类型改成“自动”然后点击“启动”。第二种命令行。用管理员身份打开PowerShellSet-Service -Name ssh-agent -StartupType Automatic Start-Service ssh-agent启用后把一个私钥加入ssh-agentssh-add $env:USERPROFILE\.ssh\id_ed25519这时会要求输入一次passphrase输入之后ssh-agent会记住这个私钥。之后在同一用户会话内执行SSH操作就不再需要输入密码了重启电脑后需要重新ssh-add一次所以服务设为自动启动也只是减少了手动步骤解锁还是要一次。从Win11的角度说比较推荐把ssh-agent设置成自动启动不然每次重启后都要重新加载私钥。设置一次后面所有Git操作都顺畅很多。4. 多账号、多仓库场景下的SSH配置4.1 一个Gitee账号多台电脑这个场景其实最简单。一台电脑生成一对密钥把公钥添加到Gitee账号下即可。Gitee允许一个账号添加多个公钥所以你在家、在公司、在笔记本上分别生成密钥并添加互不干扰。删除某一台电脑的访问权限时只需要在后台删掉对应公钥操作非常灵活。但这里有个常见误区有些人会以为每台电脑都要用同一套密钥。其实完全没有必要而且不建议这么做。每台电脑一套独立密钥是更安全更有管理的做法哪台电脑出了安全问题单独吊销那台电脑的公钥就行。4.2 一台电脑同时配置Gitee、Github等平台这个场景是真正的重头戏。很多人一台电脑既要用Gitee又要用GitHub或其他代码托管平台如果每个平台都用默认密钥最后只会保留一个另一个连连失败。解决办法是为不同的平台生成不同的密钥文件然后通过~/.ssh/config文件来区分。首先逐个生成密钥注意指定文件名ssh-keygen -t ed25519 -C 用于Gitee -f ~/.ssh/gitee_id_ed25519 ssh-keygen -t ed25519 -C 用于GitHub -f ~/.ssh/github_id_ed25519然后在.ssh目录下新建或编辑config文件没有就新建无后缀名Host gitee.com HostName gitee.com User git IdentityFile ~/.ssh/gitee_id_ed25519 Host github.com HostName github.com User git IdentityFile ~/.ssh/github_id_ed25519配置完成后分别测试ssh -T gitgitee.com ssh -T gitgithub.com两个都能返回成功提示说明SSH已经能根据不同域名自动选择对应密钥。再补充一个容易被忽略的点Git的提交作者信息user.name和user.email是全局的如果你在Gitee和GitHub用的是不同邮箱提交到不同平台时作者信息可能对不上。解决办法是在每个仓库目录下单独设置局部配置git config user.name Gitee用户名 git config user.email Gitee注册邮箱这样局部配置会覆盖全局配置确保提交记录归属于正确的账号。4.3 免密登录相关的安全细节SSH Key免密的便利性显而易见但代价是只要私钥泄露别人就能冒充你操作代码仓库。几个安全习惯值得养成私钥文件不要同步到网盘、云盘、公开仓库。给私钥设置passphrase配合ssh-agent使用兼顾安全和便利。定期在Gitee后台检查SSH公钥列表删掉不认识的条目。如果怀疑私钥泄露立刻在后台删除对应公钥并重新生成密钥。换电脑后旧电脑上的私钥如果不再使用建议后台删掉对应公钥。5. 常见问题排查与避坑实录5.1 最常遇到的现象级报错报错信息可能原因解决方案Permission denied (publickey)公钥未添加到Gitee或ssh-agent没有加载私钥检查Gitee后台公钥ssh-add -l确认私钥列表Host key verification failed首次连接未确认指纹或known_hosts内容异常删除~/.ssh/known_hosts中对应条目后重新连接UNPROTECTED PRIVATE KEY FILE私钥文件权限过宽Win11更严格用icacls命令收紧权限Could not open a connection to your authentication agentssh-agent服务未启动在服务中启用OpenSSH Authentication Agentgitgitee.com: Permission denied (publickey,password)密钥认证失败后回落到密码认证和第一条一致重点查公钥和密钥路径repository not found仓库路径错误或没有该仓库访问权限检查仓库地址拼写确认账号是否有仓库权限端口22连接超时防火墙拦截SSH连接检查防火墙放行22端口或改用Gitee备用SSH端口443最后一个“端口22连接超时”值得多说两句。有些办公网络或校园网会封禁22端口导致SSH连接失败。Gitee为此提供了备用的SSH端口443使用方式是把SSH地址改为ssh -T -p 443 gitgitee.com克隆地址改为ssh://gitgitee.com:443/用户名/仓库名.git。端口能通的话这也是一种备选方案。5.2 Win11系统相关的特有踩坑Win11下有几个坑在教程里很少被提到我在这里挨个说明。第一个坑是首次ssh -T gitgitee.com时Win11会弹出Windows防火墙授权窗口。如果你不小心点了“取消”后续所有SSH连接都会被防火墙拦截。解决办法是手动放行打开“Windows安全中心 → 防火墙和网络保护 → 允许应用通过防火墙”找到Git相关的条目确保“专用”和“公用”都勾选然后手动执行一次SSH连接触发规则。第二个坑是终端编码问题。在中文版Win11下Git Bash默认显示中文正常但PowerShell和Windows Terminal有时会出现中文乱码。这个一般不影响Git操作本身但如果你在git commit信息里写了中文推送到Gitee后页面显示乱码大概率是提交信息编码设置不对。可以在Git中设置git config --global i18n.commitencoding utf-8 git config --global i18n.logoutputencoding utf-8第三个坑是换行符CRLF/LF。Windows下默认换行符是CRLFGit在提交时会根据配置转换成LF检出时再转回CRLF。如果你在.gitattributes里没有做统一约束可能会出现warning: LF will be replaced by CRLF的提示这是正常的不影响使用。但如果整个团队在Windows和Mac/Linux之间协作建议在仓库根目录添加上下文相关的.gitattributes文件统一管理换行符规范。第四个坑是Win11的用户目录路径。如果你的Windows用户名是中文比如C:\Users\张三有些老版本Git工具可能不支持含中文的路径导致密钥加载失败或仓库操作异常。解决办法有几种一是建议使用英文用户名但改名比较麻烦二是把密钥和仓库放在非中文路径下三是升级到最新版Git。现在新版Git对Unicode路径的支持已经比较好了但中文路径踩坑的案例仍然存在所以有条件的话尽量别用中文用户名。5.3 我日常使用中的几个小习惯这里分享几个我自己长期用下来的习惯踩过几次坑之后总结出来的可能对你也有帮助。第一~/.ssh目录下的文件命名一定要有辨识度。我见过不少人所有平台的密钥都叫id_rsa换平台时互相覆盖最后不知道哪个公钥是哪个平台的。我现在统一用平台_用途_环境的格式命名比如gitee_pc_work、github_laptop一眼就能看出来。第二测试SSH连接时多利用-v参数。ssh -vT gitgitee.com会打印详细的连接和认证过程包括读取了哪个私钥文件、服务器接受了哪个公钥。定位问题的时候这比盲猜有效得多。第三不要忽略git remote -v的输出。很多人报“推送不上去”的错结果一查远程地址还是HTTPS。SSH和HTTPS是两套认证体系你在SSH配置上折腾半天命令走的却是HTTPS通道当然不生效。所以换地址之后一定要git remote -v确认一下。第四遇到问题先试ssh -T gitgitee.com而不是git clone。这个习惯能帮你把“SSH认证问题”和“Git操作问题”快速分开。SSH认证通过了再去排查仓库地址、权限等问题定位会快很多。第五定期备份~/.ssh目录下的config文件和公钥。私钥本身不建议备份到不安全的地方但config文件记录了你所有平台的密钥映射关系丢失后重新配置很麻烦放到加密的密码管理器里备份是个不错的选择。到这里Win11下从零配置SSH Key拉取Gitee仓库的完整流程就算走完了。从Git安装、密钥生成、添加到Gitee后台到克隆、提交、推送再到多账号共存和常见问题排查每一步我都尽量把“为什么这么做”和“常见坑在哪里”说清楚。SSH配置这个东西本质上就是一次性的只要打通一次后面用起来会非常顺手。我个人这几年在Windows系统上配SSH的经验是九成问题出在公钥没配对、私钥路径没指向对、ssh-agent没启动这三件事上。你只要把这三件事确认好剩下的都是常规操作。