Win11下Git安装与SSH Key配置：从零拉取Gitee仓库实战指南

刚把一台全新的Win11笔记本配置好Git又从Gitee上拉下项目代码整个过程跑通后我觉得有必要把这次实操完整记录下来。很多新手第一次接触Git和Gitee总在这套流程上卡壳不是密钥生成失败就是克隆时提示权限拒绝要么搞不清HTTPS和SSH到底有什么区别。这次我就在Win11环境下从零开始把Git安装、SSH Key生成、Gitee公钥配置、代码拉取整个链路走一遍把每一步的原理和踩过的坑都讲清楚保证你看完能直接照做。1. 环境准备Win11下的Git安装与初始配置1.1 为什么选择SSH而不是HTTPS在开始实操之前先解决一个基础问题Gitee支持HTTPS和SSH两种克隆协议为什么我们要专门配置SSH Key区别关键在于身份认证方式和后续操作体验。用HTTPS克隆仓库每次push、pull时都要输入Gitee的用户名和密码虽然可以用凭据管理器记住但如果你换了电脑、清除了凭据或者同时管理多个账号就很容易被反复登录搞得很烦躁。而且密码在网络传输中理论上存在被截获的风险虽然HTTPS本身是加密的但密码这种静态凭据的暴露面始终大于密钥机制。SSH Key走的是公钥加密、私钥签名的认证方式。你把自己电脑上生成的公钥放到Gitee账号里私有密钥留在本地。每次连接时服务器用公钥验证本地私钥签发的请求匹配成功就直接放行全程不需要手动输入密码更安全也更顺畅。Gitee本身也建议用户使用SSH方式推送代码尤其当你经常需要操作仓库时这种免密体验是刚需。简单类比一下HTTPS像用门禁卡刷门每次进出都要掏卡验证SSH Key像录入人脸后刷脸进门系统认出你后直接放行往后不需要反复证明“我是我”。1.2 下载Git及安装关键选项说明Win11环境下安装Git我建议直接去Git官网下载选择Windows 64-bit版本不要下载Portable版便携版在后续集成和右键菜单支持上偶尔会有小问题完整安装版更省心。Git for Windows的安装包是一个exe文件下载后双击进入安装向导。大部分选项默认即可但有几步需要注意很多人就是默认点到底后面用起来才发现不顺手。第一个关键选项是“Select Components”默认勾选的项目里“Git Bash Here”和“Git GUI Here”必须保留这两个会在右键菜单添加入口后面的密钥生成、命令行操作都靠Git Bash。第二个关键是“Choosing the default editor used by Git”默认选Vim。对不熟悉Vim操作的人来说后面每次提交代码进入编辑器界面会非常痛苦不知道怎么保存退出。建议在这里改成Notepad或VS Code实在不想折腾就保持Vim但一定要记住Vim保存退出命令是:wq不然提交时卡在编辑器里会很崩溃。第三个关键是“Adjusting the name of the initial branch in new repositories”默认是master建议改成main因为Gitee和GitHub上的新仓库默认分支都已经全面转向main了保持一致可以避免很多分支名不一致带来的认知困惑。第四个关键是“Choosing the SSH executable”这里务必选择“Use OpenSSH”保持默认的这个OpenSSH模式这样后面生成的SSH Key和Gitee的兼容性最好。不要选“Use PuTTY”除非你明确知道自己要用PuTTY的密钥体系。最后一个关键选项是“Configuring the line ending conversions”默认的“Checkout Windows-style, commit Unix-style line endings”是最稳妥的选择这在跨平台协作时能最大程度避免换行符引发的diff混乱保持默认即可。安装完成后在任意目录右键菜单里会出现“Git Bash Here”点击打开输入以下命令验证版本git --version能看到版本号输出就说明Git核心安装成功了。接下来还需要配置用户信息这一步很多人会跳过但如果不配置首次提交代码时Git会用系统默认信息在Gitee上就会显示成陌生身份甚至会被仓库拒绝提交。执行以下两条命令git config --global user.name 你的Gitee用户名 git config --global user.email 你注册Gitee用的邮箱这里有个细节user.name和user.email必须与你Gitee账号信息保持关联性否则提交记录在Gitee上无法对应到你的账号。配置完成后可以用下面命令查看确认git config --global --list2. SSH Key生成把门槛过掉的核心环节2.1 理解SSH Key的成对机制SSH Key本质上是一对非对称加密密钥分为公钥和私钥两部分。公钥是公开的可以放心地告诉别人甚至贴到服务器上私钥则必须保密它存储在本地永远不要外传。形象一点理解公钥是你家的门锁可以随便给别人看私钥是唯一的钥匙只在你手里。当Gitee服务器收到你推送代码的请求时它用你预先配置好的“门锁”公钥来验证你手里的“钥匙”私钥验证通过就允许你操作仓库。所以整个流程就是本地生成密钥对 → 公钥交给Gitee → 私钥留在本地 → 建立SSH连接时自动完成身份认证。Win11系统本身自带OpenSSH功能Git安装时也已经内置了OpenSSH组件因此我们不需要额外安装任何东西只需要通过命令把密钥对生成出来即可。2.2 生成密钥的具体操作打开Git Bash输入以下命令ssh-keygen -t ed25519 -C Gitee SSH Key这里说明一下参数含义。-t ed25519指定密钥算法类型ed25519是目前推荐的现代公钥算法比传统的RSA更安全、密钥长度更短、生成和验证速度更快。虽然RSA 4096依然是很多人的选择但新环境我更推荐ed25519Gitee和GitHub都已经全面支持。-C后面跟的是注释信息相当于给这把钥匙贴上标签方便识别可以填你的邮箱也可以填任何备注文字。命令输入后系统会提示Generating public/private ed25519 key pair. Enter file in which to save the key (/c/Users/你的用户名/.ssh/id_ed25519):这里直接按回车就行使用默认路径。绝大多数情况下没有必要修改路径因为Git和Gitee默认都会去这个目录找密钥文件改了反而增加后续配置负担。紧接着系统会提示Enter passphrase (empty for no passphrase):这一步是询问是否给私钥再加一道密码保护。如果设置了passphrase每次使用私钥时都要输入这个密码安全等级更高但操作起来多了一步日常高频使用会有点烦。如果你只是本地开发使用建议直接留空按回车方便快捷如果是共享电脑或者安全要求高的场景建议设置一个毕竟私钥泄露的代价远大于多输一次密码的麻烦。密钥生成完成后默认路径下会出现两个文件id_ed25519是私钥id_ed25519.pub是公钥。此时可以用以下命令查看公钥内容cat ~/.ssh/id_ed25519.pub输出结果是一长串以ssh-ed25519开头、结尾是你刚才填写的注释的字符串。这块内容就是接下来要配置到Gitee上的公钥。2.3 公钥复制与私钥保护公钥内容显示在终端里之后需要完整复制这一整行包括前面的ssh-ed25519 AAAA...和末尾的注释部分都不能遗漏。在Windows下选中复制时一定要留意不要漏掉行首和行尾的字符建议使用鼠标左键从行首拖到行尾再按CtrlInsert或者右键复制确保完整。复制好公钥后请检查一下私钥文件是否权限正确。在Windows环境下私钥文件默认在用户目录的.ssh文件夹里如果担心访问权限可以在Git Bash中执行ls -la ~/.ssh/正常情况下应该看到id_ed25519和id_ed25519.pub两个文件权限显示为-rw-------。如果私钥权限过于开放系统有时会拒绝使用该密钥连接服务器不过Win11下Git处理得已经比较好这种情况很少出现但值得留意。关于私钥保护我再多说一句特别重要的经验私钥文件和密码等同对待任何情况下都不要截图、不要发群里、不要上传到网盘。如果有人拿到你的私钥就相当于拿到了你所有配置了对应公钥的代码仓库的操作权限后果比密码泄露更严重。密码泄露了还可以改密码私钥泄露了你得撤销密钥全部重新生成一遍。3. 配置Gitee账号并完成首次连接验证3.1 Gitee上添加SSH公钥的入口与命名登录Gitee网站后点击右上角头像进入“设置”页面在左侧菜单栏找到“安全设置”分类下的“SSH公钥”选项点击进入后就是公钥管理页面。这个页面有三个字段需要填写标题、公钥内容和有效期。标题可以随便填主要目的是方便你日后辨识这是哪台设备、哪个环境生成的密钥比如“家用台式机”、“2024款笔记本”或者“公司电脑”不建议填得太随意因为后续你要维护多台设备时清晰的命名能帮你快速找到对应条目。公钥内容那一栏把刚才复制的那长串ssh-ed25519开头的字符串粘贴进去注意不要有多余空格和换行Gitee对格式比较敏感格式不正确会导致后面的验证失败。有效期建议选择“永久有效”。有些担心安全的用户会设置一个较短的期限但这样做的结果是到期后你会突然发现自己无法推送代码需要重新生成密钥再配置一次平时用起来很别扭。除非是临时授权的公共环境否则永久有效就够了安全性的保障更多依赖私钥本身不被泄露。填完点击“确定”按钮Gitee会要求输入账号密码确认操作输入后公钥就添加成功了。此时页面上会列出所有已配置的公钥以及对应的标题和创建时间。3.2 用ssh -T命令验证连接公钥配置完成后先不要急着拉取仓库第一步要做的是验证SSH连接是否通。在Git Bash中输入以下命令ssh -T gitgitee.com这里有一点非常关键Gitee的所有SSH连接都使用git这个用户名后面的gitee.com是Gitee的域名。不要把自己的Gitee用户名填在这里那是常见的错误做法会直接导致认证失败。首次执行这条命令时系统会提示Are you sure you want to continue connecting (yes/no/[fingerprint])?这是因为本地还没有保存Gitee服务器的主机指纹SSH服务在确认安全性之前会先征询你的意见。输入yes回车即可你可以在~/.ssh/known_hosts文件中看到新写入的记录。如果一切顺利Gitee会返回一段欢迎信息Hi 你的用户名! Youve successfully authenticated, but GITEE.COM does not provide shell access.看到这句话就说明SSH认证已经通过了。注意这里提示的是“does not provide shell access”意思是这台服务器不提供命令行交互只能用来做Git操作这是正常现象不需要惊慌。如果你的输出是Permission denied (publickey)那就说明公钥没有配置成功或者本地私钥没有被正确识别。具体排查方法在后面的章节中详细展开。3.3 克隆仓库实操指南SSH连接测试通过后就可以正式拉取仓库代码了。在Gitee上找到目标仓库点击页面上方的“克隆/下载”按钮在弹出的下拉框里选择“SSH”标签页可以看到一个类似下面的地址gitgitee.com:用户名/仓库名.git复制这个SSH地址回到Git Bash在你希望存放代码的目录下执行克隆命令git clone gitgitee.com:用户名/仓库名.git这里简单拆解一下这个URL的结构。gitgitee.com是连接Git服务器的固定地址冒号后面的用户名是你的Gitee空间名仓库名就是你要拉取的代码仓库最后的.git是Git仓库的标识后缀。这个地址必须与仓库页面上显示的完全一致手动输入容易出错所以强烈建议直接复制。克隆过程中如果仓库较大会看到进度条和文件接收过程等待完成即可。克隆完成后仓库文件夹已经出现在当前目录下进入仓库目录cd 仓库名执行git branch -a可以看到所有分支列表本地默认分支通常是最新代码。到这里Win11环境下Git配合SSH拉取Gitee仓库的整个流程已经全部跑通了。4. 常见问题排查与多账号管理实战4.1 Permission denied (publickey) 的完整排查这是出现频率最高的错误基本每条SSH Key教程下面都能看到大量这个报错。出现这个问题的原因不外乎以下几种。公钥没有真正添加到Gitee账号上。很多人复制了公钥内容但保存前没有仔细检查是否少了字符或者粘贴时带了换行。重新检查Gitee后台的SSH公钥条目对比本地公钥文件内容是否完全一致。本地私钥路径不是Git默认查找的路径。如果你在生成密钥时手动修改过保存路径Git会去默认的~/.ssh/id_ed25519找密钥找不到自然认证失败。这种场景下有两种修复方式要么把生成好的密钥文件移动到默认目录要么在~/.ssh/config文件中显式指定密钥文件路径。SSH命令执行了正确的测试但公钥添加到另一个账号。这个情况尤其容易发生在同时有GitHub和Gitee账号的人身上复制粘贴时搞混了。检查你的公钥内容是否和Gitee后台的一致最简单的办法是在Git Bash里执行cat ~/.ssh/id_ed25519.pub然后和Gitee后台逐字符对一遍。配置了多个密钥但默认私钥不是目标仓库对应的人。当本地存在多个密钥对时Git默认会使用id_ed25519或者id_rsa这个命名如果你某个仓库使用的是别名密钥需要在仓库目录下的.ssh/config中配置Host别名。这部分稍后会详细讲。遇到Permission denied (publickey)时还有一个重要的调试手段用ssh -vT gitgitee.com开启详细日志终端会输出整个认证过程其中搜索Offering public key和Authentications that can continue两行可以快速定位是哪个密钥文件被尝试、被拒绝非常高效。4.2 连接超时或无法解析主机很多时候SSH不是认证失败而是网络层面根本没连到Gitee服务器。现象是命令执行后长时间无响应最后输出Connection timed out或者Could not resolve hostname。这种问题通常出在网络环境上。公司网络、学校网络可能有严格的出口控制会导致SSH的22端口无法访问外网。可以尝试用以下命令测试Gitee的SSH端口是否通畅ssh -T -p 443 gitgitee.com如果443端口能连通说明22端口确实被网络限制了Gitee官方也支持通过443端口走SSH协议。但这种方式需要额外配置日常家用网络一般不需要开启。如果是Could not resolve hostname这是DNS解析层面的问题和SSH配置无关。先检查系统网络是否正常能不能打开其他网站再尝试用nslookup gitee.com看DNS解析结果。DNS缓存出错时可以执行ipconfig /flushdns刷新再重新连接。还有一种被很多人忽略的情况本地SSH版本过旧导致与新服务器的密钥交换算法不兼容。Win11系统自带的OpenSSH版本通常比较新但如果你的Git是很多年前装的旧版本建议直接更新Gitgit update-git-for-windows一步搞定。4.3 同时配置Gitee和GitHub的多密钥管理很多开发者的本地环境并不只连Gitee一个平台GitHub几乎是标配。问题在于两个不同平台的账号需要不同的公钥而Git默认在连接时只会使用默认命名的私钥文件这样就会导致配置了第二个平台的公钥后第一个平台连不上了。这里推荐的做法是生成两个不同名称的密钥文件然后通过~/.ssh/config文件来管理每个主机的认证映射。生成针对GitHub的密钥时指定不同的文件名ssh-keygen -t ed25519 -C GitHub SSH Key -f ~/.ssh/id_ed25519_github然后在~/.ssh目录下创建config文件写入以下内容Host gitee.com HostName gitee.com User git IdentityFile ~/.ssh/id_ed25519 Host github.com HostName github.com User git IdentityFile ~/.ssh/id_ed25519_github这样配置后Git在连接Gitee时自动使用id_ed25519连接GitHub时则使用id_ed25519_github互不干扰。创建config文件可以用任意文本编辑器注意编码建议使用UTF-8Windows记事本默认的编码在部分场景下会导致解析异常。配置完成后分别测试两个平台的连接ssh -T gitgitee.com ssh -T gitgithub.com两个都返回欢迎信息就说明多账号管理成功了。4.4 克隆私有仓库时的权限细节Gitee上的仓库分为公开和私有两种。拉取公开仓库任何人只要有SSH地址就能直接克隆不需要任何认证。但拉取私有仓库时必须保证当前SSH密钥对应的Gitee账号是该仓库的所有者或者是被添加为仓库协作者并拥有读取权限。如果克隆私有仓库时遇到remote: Access denied或者fatal: Could not read from remote repository不要急着怀疑SSH密钥的配置先确认你的账号是否对这个仓库有访问权限。有时候你的密钥配置完全没问题但仓库是别人私有项目你没被授权自然拉不下来。另外还要区分一下身份绑定的问题SSH密钥是绑定到具体Gitee账号的而仓库权限又是账号维度的。所以在Gitee上添加SSH公钥时一定确认是在需要授权的那个账号下添加的。不同账号、不同邮箱注册的都是独立的身份体系。4.5 换电脑或重装系统的迁移技巧Win11环境重装系统或者换新电脑是常事很多人重装完才发现自己没法拉取代码了因为本地私钥已经随着旧系统烟消云散。这时候你有两种处理路径。第一种旧私钥还在直接迁移。把旧电脑~/.ssh目录下的id_ed25519和id_ed25519.pub两个文件拷贝到新电脑的相同位置然后用ssh -T gitgitee.com验证即可。这比重新生成密钥再配置一次省事得多而且不需要动Gitee后台的公钥配置。第二种旧私钥已经丢失重新生成。在新电脑上按前面流程重新执行ssh-keygen -t ed25519 -C Gitee SSH Key生成新密钥对把新公钥内容复制到Gitee后台可以顺手把之前旧设备对应的公钥条目删掉保持公钥列表干净清爽。这里有一个小建议如果你经常更换电脑建议在网盘或加密U盘里备份一份私钥文件。但是注意这个备份必须有足够强的安全意识私钥泄露的后果和密码泄露一样严重加密存储是最低要求。不推荐仅仅通过邮件附件或者聊天工具传输私钥文件。写在最后的个人体会这套流程走下来最想分享的一点体会是SSH Key配置本身并不复杂真正考验人的是排查问题和理解原理的能力。很多人卡在中间某一步就是因为不知道每一条命令为什么存在、每一个配置项在解决什么问题。我始终建议新接触Git的人不要只背命令试着去理解密钥对机制、理解URL结构、理解config配置文件的作用这样哪怕遇到教程中没覆盖到的错误也能靠自己的逻辑推理找到解决办法。还有一个小建议公钥配置成功后第一次推送代码前先看看仓库是空的还是有README的如果在网页端创建仓库时勾选了初始化README本地克隆时不会遇到问题但如果你先本地创建了项目又去网页端建了带README的仓库直接push会被拒绝因为两边历史互不相干。解决办法也不难用git pull origin main --allow-unrelated-histories把远端内容拉下来合并后再推送就行。Git和Gitee的组合是日常开发最基础的工作流把这套配置摸透了后续不管接触什么代码托管平台核心原理都是相通的。希望这篇教程能帮你顺利迈过SSH Key这道门槛。