Git入门到Gitee托管：SSH公钥配置与代码上传全流程

前两天有个刚入门的朋友问我代码写好了想传到 Gitee 上存起来结果在命令行里敲git push一直被拒绝弹出的提示看着像天书查了半天才发现是 SSH 公钥没配置。这个场景我太熟了——刚接触 Git 的时候我连公钥私钥是干嘛的都搞不清对着教程一步步点点完了还是报错。这篇就把我踩过的坑整理出来从 Git 安装、Gitee 建仓库到 SSH 公钥的生成与配置再到代码上传的完整流程一次讲清楚。适合刚接触 Git、想在 Gitee 上管理代码的初学者也适合装过 Git 但一直没搞明白 SSH 是怎么回事的同学。1. 先把关系理清Git、Gitee 和 SSH 公钥分别是干什么的1.1 Git 解决的是后悔药和协作两件事很多人第一次听到 Git是在面试题或者同事嘴里感觉是个很高深的东西。其实它的核心作用就两个版本回退和多人协作。版本回退很好理解——你写代码改了一下午改到第十版发现还是第一版最好如果没有版本管理你只能靠复制另存为 xxx_final_v2_真final.zip这种痛苦的方式。Git 用 commit提交把每次修改记成快照想回哪一版都行。多人协作则是 Git 更值钱的地方。本地随便怎么改都不会影响别人提交之后推送到远程仓库队友拉下来各自在各自的分支上干活最后合并。这个链条看着复杂但只要把最基础的命令跑熟日常单人开发也已经能明显感受到效率提升。1.2 Gitee 是放代码的云仓库不等于 GitGit 本身是装在你电脑上的一个命令行工具它的历史记录都存在本地目录里。但本地终究有风险——硬盘坏了、电脑丢了、你换了一台电脑代码就没了。所以需要把代码放到一个远程托管平台上。Gitee码云就是国内常用的一家功能上和 GitHub 类似但服务器在国内访问速度更快中文界面也更友好。打个比方Git 像是你自己家里的一套档案管理系统Gitee 则是把档案存到银行保险柜里既能备份也能分享给其他人一起编辑。很多人以为Git 就是 Gitee或者Git 就是 GitHub这是最常混淆的一点。它们一个是软件一个是网站服务后面我会反复提到本地和远程这两个词说的就是这两层。1.3 SSH 公钥到底是个什么锁SSH 公钥解决的是怎么证明你是你这个认证问题。每次 Git 要跟远程仓库通信服务器都要确认来的人是不是账号本人最笨的办法是每次输账号密码Git 也支持但输一次两次还行天天推代码还要输密码就太烦了。SSH 的认证方式是你本地生成一对密钥一个叫私钥自己留着一个叫公钥交给 Gitee。当你发起连接时私钥对请求做签名服务器拿你事先存好的公钥去验证签名。签名对得上就放行。这就好比你自己配了一把钥匙把锁芯的副本留给门卫之后每次进门前卫验锁芯不用你再报一遍姓名密码。私钥一旦泄露等于钥匙被别人配走了这也是为什么所有教程都会强调私钥文件绝不能上传、绝不能发给别人。1.4 配置 SSH 到底值不值这里可能有人会问我用 HTTPS 地址克隆记住密码以后也能免密啊为什么还要折腾 SSH我的建议是如果是长期用命令行、或者经常跟远程仓库交互SSH 一劳永逸。HTTPS 在部分环境下会反复弹认证提示尤其在配置了二次验证的账号上命令行里输密码还容易踩认证失败的坑。SSH 配好了clone、push、pull 全程无感换 IDE 也不用重新配账号。这一套配置大概十分钟收益是之后一年都省心。2. 环境准备Windows 和 macOS 上把 Git 装好2.1 Windows 安装安装器里两个选项别选错Windows 装 Git 最主流的方式是去 git-scm.com 下载安装包。安装界面虽然全是英文但整个过程基本只需要一路 Next有两个地方需要停一下看一下。第一个是 Adjusting your PATH 这一步一定要选中间那项 Git from the command line and also from 3rd-party software。如果你选成第一项 Use Git from Git Bash only后续在 cmd 或 PowerShell 里敲 git 会提示命令找不到这也是新手最常见的报错来源之一。第二个是 Choosing the default editor默认 Vim 可以保留嫌难用可以后面再配 VS Code。反正第一次安装核心目标就是装完能在任意终端里敲出git --version。git --version # 输出类似 git version 2.45.0.windows.1 就说明装好了装完之后还会发现开始菜单多了一个 Git Bash这就是一个类 Linux 的终端环境。我用 Windows 时习惯直接用 Git Bash 敲命令因为它的命令提示和行为跟 macOS / Linux 更接近教程里写ls、cat这些命令也能直接跑不用再花力气记一套 Windows 版本的等效命令。后面我命令里的路径写法也默认是在 Git Bash 环境下执行的如果用的是 cmd 或 PowerShell注意把cat换成本身的查看命令或者也用 Git Bash 操作。2.2 macOS 安装两种方式自选macOS 上有两条路一条是用 Homebrew 安装brew install git另一条是安装 Xcode Command Line Tools它会自带一个 Git 版本xcode-select --install个人更推荐 Homebrew因为版本新、后续升级方便brew upgrade git一行搞定。刚装完如果终端里执行git --version没反应先检查一下命令是否被系统自带的旧版本覆盖常见做法是用which git查看命令路径确保指向你刚安装的位置。2.3 装完第一件事配置用户名和邮箱不然 commit 会失败这一步很多人会跳过直到第一次git commit被拒绝才回来配。提交信息里必须带着作者信息所以 Git 要求你提前声明你是谁。在任意终端执行git config --global user.name 你的名字 git config --global user.email 你的邮箱--global表示全局生效这样以后这台机器上所有仓库都默认用这个身份。建议邮箱和 Gitee 注册邮箱保持一致这样代码提交记录能和账号关联上。配置完成之后可以用git config --list查看所有配置项确认无误。这些配置最终会写进用户主目录下的.gitconfig文件如果你是个配置控也可以直接编辑文件但我还是建议先用命令因为命令会顺便校验格式。之后再装小乌龟TortoiseGit这类图形客户端时这套配置也会直接继承不会出现两边身份不一致的问题。3. 在 Gitee 上创建仓库初始化选项别乱勾3.1 注册和新建仓库的入口登录 gitee.com 注册账号之后右上角的号或者主页的新建仓库按钮都可以进入创建页面。创建的时候需要填仓库名称和路径路径会出现在访问地址里比如我建一个叫 hello-git 的仓库地址就是https://gitee.com/用户名/hello-git。仓库名称可以随时改但路径一旦被别人引用改了会影响访问所以第一次命名尽量想清楚。这个环节还有个很容易被忽略的点仓库的归属选择。个人账号直接就是自己的如果加入了某个组织或者企业也可以选择建到组织下面。对个人学习来说建在自己的账号下最省事后面涉及到 SSH 公钥权限时也不容易混乱。3.2 README、.gitignore、开源许可证到底选不选创建页面有几个初始化选项我的建议是README如果项目是公开的建议勾选它会作为仓库首页的说明文档。如果是纯私有备份不勾也影响不大。.gitignore这个非常推荐。它会告诉 Git 哪些文件不要纳入版本管理比如 IDE 配置、编译产物、依赖包。Gitee 会根据你选择的语言生成一份模板选对语言即可。开源许可证如果要开源MIT 或 Apache-2.0 都行MIT 更宽松如果只是私有仓库直接不选。另外还有一个容易忽略的选项是仓库可见性私有还是公开。私有仓库在 Gitee 上个人使用是免费的但在网页上不会被别人搜索到。如果你只是想把代码当网盘用、不想分享选私有就好。很多人一开始觉得公开也没关系结果把写了一半的代码暴露出去后面又来删库反而麻烦。Gitee 支持仓库可见性设置和批量删库操作网页上都能完成但尽量在创建的时候就想清楚。3.3 仓库页面要认识的三个地方创建完成跳到仓库主页后重点先看三个区域第一个是克隆/下载按钮。点开会同时显示 HTTPS 地址和 SSH 地址两种格式前者长这样https://gitee.com/用户名/仓库名.git后者长这样gitgitee.com:用户名/仓库名.git地址是后续所有远程操作的关键建议先复制到备忘录里存好。第二个是默认分支名。Gitee 新建仓库通常默认分支是 master也有人改成 main这不重要但你要记住自己仓库的默认分支是什么因为推送的时候分支名必须对得上。第三个是文件标签页。仓库里有哪些文件、谁改过、改了什么都从这里看。对初学者来说这个网页上的历史记录列表就是理解 Git 日志最好的辅助工具。网上搜 Gitee 使用教程时经常能看到如何克隆项目怎么把文件上传至 Gitee这类问题答案基本都藏在仓库页的地址和分支信息里。4. 核心环节SSH 公钥的生成与绑定4.1 先查一查这台电脑是不是已经有密钥了在动手生成之前先看一眼~/.ssh目录。Windows 上一般是C:\Users\你的用户名\.sshmacOS / Linux 是/home/你的用户名/.ssh。终端执行ls -al ~/.ssh如果看到id_ed25519和id_ed25519.pub或者id_rsa和id_rsa.pub这样成对的文件说明已经生成过密钥。.pub结尾的是公钥可以继续用没必要重复生成。如果目录不存在或者里面是空的那就进入下一步。这里我多说一句很多人换电脑之后懒得配密钥直接把旧电脑的整个.ssh目录复制过来这其实是最快的恢复方式只要私钥文件权限设置正确一般都能直接用。如果你是 Windows 10/11 自带 OpenSSH生成的目录结构和 Git Bash 是一样的两边可以通用。4.2 生成密钥用 ed25519 还是 RSA现在主流推荐用 ed25519 算法它比 RSA 更短、更快、安全性也不差除非你要连一些特别老的服务器才需要用 RSA 4096。命令如下ssh-keygen -t ed25519 -C 你的邮箱接下来会问保存路径直接回车用默认位置即可别改到一个自己都找不到的地方。然后会问要不要设置 passphrase口令我建议个人开发环境直接留空否则每次使用私钥都要输入口令反而把免密的意义搞没了。如果你安全意识强想设置那就配合 ssh-agent 使用避免反复输入。生成完成后~/.ssh下会出现两个文件id_ed25519私钥和id_ed25519.pub公钥。再次强调私钥永远不要发给任何人也不要传到任何代码仓库里。公钥则可以放心分发Gitee、GitHub 这类平台就是靠存公钥来识别你的。4.3 把公钥复制到 Gitee 账号查看公钥内容用cat ~/.ssh/id_ed25519.pub输出是一长串以ssh-ed25519 AAAA...开头、以你邮箱结尾的文本把它完整复制下来。然后登录 Gitee点右上角头像进入设置页面找到安全设置 → SSH 公钥标题随便填比如我的笔记本公钥内容粘贴进去确定保存。这里有个很常见的坑复制的时候不要少字符、不要多空行。最稳妥的方法是直接用cat命令输出然后用鼠标框选整个内容复制别手打。Windows 用户在 Git Bash 里如果不好选中长文本可以用cat ~/.ssh/id_ed25519.pub | clip把内容直接复制到剪贴板再粘贴到网页输入框。这套操作在 Gitee 设置 SSH 公钥的教程里经常被简化掉但实际用起来非常顺手。4.4 验证配置是否成功关注 ssh -T 的提示配置完之后在终端执行ssh -T gitgitee.com第一次连接会提示是否信任该主机输入yes回车。如果一切正常你会看到一行类似这样的输出Hi 用户名! Youve successfully authenticated, but GITEE does not provide shell access.看到 successfully authenticated 就说明公钥已经生效了。如果输出的是Permission denied (publickey)或者Connection reset by ...先别急大概率是下面几个原因之一公钥没粘贴完整、粘贴错了平台加到了别人的账号下、本地用的是 HTTPS 地址导致没走 SSH。逐个检查通常十分钟内能解决。5. 跑通全流程从克隆到推送第一次上传代码5.1 情景一远程已经有仓库把它克隆到本地在 Gitee 仓库页复制 SSH 地址然后git clone gitgitee.com:用户名/仓库名.git命令会把远程仓库的完整历史下载到当前目录并生成一个同名文件夹。进入文件夹后你可以看到.git这个隐藏目录它记录着整个仓库的版本历史千万别手贱删掉删了版本历史就全没了。克隆完成后用git remote -v看一下当前的远程地址确认是 SSH 格式而不是 HTTPS 格式。有些时候网上教程里复制下来的是 HTTPS 地址你照抄之后虽然能克隆但后面每次 push 都要认证所以这一步检查特别重要。如果发现地址不对可以用git remote set-url origin gitgitee.com:用户名/仓库名.git改成 SSH。5.2 情景二本地已经有一堆代码想推到空仓库这是入门阶段最常遇到的场景——代码早就写在本地了Gitee 上刚建了一个空仓库。流程分四步cd 你的项目目录 git init git remote add origin gitgitee.com:用户名/仓库名.git如果项目还没有任何提交先做一次初始提交git add . git commit -m 初始化项目 git branch -M main git push -u origin maingit remote add origin是把远程仓库地址和本地origin这个名字关联起来从此push、pull都可以直接用 origin 指代远程。-u参数的意思是设置上游分支设置了之后以后再推送只需写git push不用每次重复写远程分支名非常省事。如果你创建的 Gitee 仓库默认分支是 master记得把-M main改成-M master或者干脆先用git branch查看当前分支名再决定。分支名对不上推送时候会报一堆让人头大的提示。这也是网上搜索Gitee 上传代码到仓库怎么把文件上传至 Gitee时最容易被忽略的细节。5.3 日常迭代三步曲改代码、提交、推送代码托管起来之后日常开发就是一套固定循环git status # 看当前改了什么 git add . # 把改动加入暂存区 git commit -m 提交说明 # 提交到本地版本库 git push # 推送到远程仓库可以这样理解这几个命令的分工git add是把要保存的东西放进购物车git commit是结账生成一个快照git push是把快照送货到远程仓库。购物车可以反复加减没结账之前一切随意结账之后想反悔就只能用回滚操作了所以提交说明一定写清楚这次改了什么。另外多人协作或者多设备同步的情况下推送之前先养成git pull的习惯。git pull会把远程的新提交拉下来合并到本地再推上去就不会有冲突。如果直接推送时发现提示! [rejected]说明远程有本地没有的提交这时候强行推会被拒正确做法也是先 pull。5.4 分支、忽略文件和提交信息的小建议既然是基础篇分支不展开但提一句主分支保持基本可用想开发新功能就开一个分支测试稳定后再合并回主分支。这个习惯越早养成越好。.gitignore建议单独维护常见要忽略的有Java 的target/、Node 的node_modules/、Python 的__pycache__/、IDE 的.idea/、.vscode/还有各种.env环境变量文件。这些东西进了版本库轻则让仓库变得臃肿重则把密码密钥泄露出去。提交信息用动词 简要描述的格式比如fix: 修复登录超时问题、feat: 新增导出功能、docs: 更新 README几个月后回看日志时你会感谢当初写清楚的自己。6. 高频报错和排查实录这些坑我都替你踩过6.1 git 无法识别为 cmdlet、函数、脚本文件或可运行程序的名称这是 Windows 上新手的第一个拦路虎。原因基本只有一个Git 安装时 PATH 没配好或者安装完终端没有重新打开。系统环境变量里没有 Git 的可执行目录cmd / PowerShell 自然找不到它。解决办法重新运行安装包到 Adjusting your PATH 那一步选择中间选项Git from the command line and also from 3rd-party software如果安装时已经选了还不行就手动把C:\Program Files\Git\cmd加到系统环境变量 Path 里保存后关掉终端重新打开。Git Bash 如果本身能打开但 cmd 不行那也基本可以断定是 PATH 的问题。6.2 Permission denied (publickey) 的完整排查链路这个报错是 SSH 配置失败最典型的信号。按顺序排查执行ssh -T gitgitee.com确认是不是也报一模一样的错。打开 Gitee 设置里的 SSH 公钥列表核对公钥内容是否完整、标题是否对应。公钥必须是一整行以ssh-ed25519或ssh-rsa开头。检查本机~/.ssh下的私钥文件名。如果生成时改了文件名Git 默认找不到需要用ssh-add把私钥加到代理里或者在~/.ssh/config里指定IdentityFile。确认克隆地址是gitgitee.com:用户名/仓库名.git这种格式别把 HTTPS 地址当成 SSH 用。还有一个容易被忽略的点如果电脑时间和当前时间差太多SSH 握手也可能失败。这个概率不大但遇到查了所有配置都没问题时顺手对一下时间总没坏处。6.3 推送被拒! [rejected] / failed to push some refs这个报错的官方解释是远程分支包含本地没有的提交。最常见于创建仓库时勾选了 README同时本地又先执行了git init并提交过代码两边历史没有关联推送时就被拒绝。解决思路是先同步再推送git pull --rebase origin main git push -u origin main--rebase会把本地提交重新放到远程最新提交之上这样历史是一条直线看着干净。如果合并时有冲突Git 会标出冲突文件手动改完再git add、git commit继续。也有人用git push -f强行覆盖但这会抹掉远程的历史提交单人私有仓库偶尔可以多人协作的共享分支千万别这么玩。6.4 克隆私有仓库报 404 或者提示没有权限私有仓库对不可见账号来说就是 404这是为了不泄露仓库存在性。遇到这种情况确认三件事你的 Gitee 账号是否登录、是否被添加为该仓库的协作者、克隆地址里的用户名是否拼写正确。如果仓库是你自己的但还是 404大概率是没登录或者地址里用户名写错了。需要协作者时在 Gitee 仓库的管理 → 仓库成员管理里添加对方账号搜索到用户后选择角色对方就能访问了。6.5 Windows 换行符警告LF 将被替换为 CRLF在 Windows 上提交代码时Git 经常提示 warning: LF will be replaced by CRLF这是行尾符差异导致的。Windows 用回车换行CRLFLinux / macOS 用换行LFGit 默认会在检出时做转换避免代码在两边系统上显示成一行。我的建议是 Windows 上执行一次git config --global core.autocrlf truemacOS / Linux 上执行git config --global core.autocrlf input以后基本不会再为这事烦恼。这个配置不是必须的但配一下能少看很多警告心情会好很多。下面用一个表格收一下上面这些报错和对应的处理方式方便你遇到问题时快速对照报错关键信息最常见原因快速处理git 无法识别为 cmdletPATH 未配置重装选 PATH 中间项或手动加 C:\Program Files\Git\cmdPermission denied (publickey)SSH 公钥未正确配置核对公钥粘贴、私钥路径、克隆地址! [rejected] / failed to push远程有本地没有的提交git pull --rebase 后重新 push404 克隆私有仓库无权限或未登录确认协作者权限、账号登录、地址正确LF will be replaced by CRLF行尾符差异配置 core.autocrlf7. 配好 SSH 之后还能顺手做的几件事7.1 给静态站点一个家Gitee Pages如果你有个人主页、文档站或者纯前端项目想免费托管Gitee 的 Pages 服务值得试一下。在仓库页面找到服务 → Gitee Pages选择部署分支和目录点击启动就能生成一个对外访问的静态网址。Gitee Pages 国内访问速度快用来放项目文档非常合适。注意该功能需要完成实名认证部署前先确认账号状态。7.2 一个公钥可以同时用于多个平台SSH 公钥的机制决定了同一对密钥可以添加到多个平台比如 Gitee、GitHub 甚至公司内网的 Git 服务都可以注册同一个公钥。以后换新电脑时备份好~/.ssh下的两个密钥文件到新机器上放到同路径再把公钥加到各平台就能无缝恢复。前提还是一样的私钥只在自己机器上别上传、别外传。7.3 给日常提交建立固定节奏最后分享一些我自己的习惯。每天开始写代码前先git pull拉一遍远程更新避免别人已经改了而你还在旧版本上写下午或者晚上收工时确认当天改动已经commit并push保证代码至少备份在远程。这个习惯最初看起来繁琐但坚持一两周后你会发现代码丢了改错了找不到之前版本这种事彻底从你的工作里消失了。我个人用得最多的一个技巧是git log --oneline --graph可以把提交历史和分支关系以图形化方式压缩成一行行显示比网页上的历史列表更直观。刚开始不必要背命令能把status、add、commit、push、pull、clone这几个用熟日常开发已经足够跑起来了。SSH 公钥配好之后这些命令执行起来全程无感你会慢慢习惯这种只管写代码、不用管传输认证的节奏。