Gitee仓库创建与项目推送完整指南：从SSH密钥到首次push

创建Gitee仓库并推送项目听起来是个很基础的操作。但我在实际接触过程中发现很多人在这一步卡住并不是因为不会敲命令而是因为对整个流程缺少一个整体的认知SSH密钥到底解决什么问题、仓库初始化要不要勾选README、第一次推送被拒绝是因为什么。这篇文章我会把一个完整的流程拆开讲清楚从零开始最终把你本地的项目推到Gitee上。这篇文章适合刚接触Git的开发者也适合那些之前在Windows上装完Git就不知道怎么继续的同学。我会把所有实操过程、参数选择背后的逻辑、以及我在真实开发中踩过的坑一并写出来你跟着操作就行。1. 内容整体设计与思路拆解1.1 一个完整流程包含哪些环节创建Gitee仓库并推送项目表面上是“网页上点几个按钮终端里跑几条命令”但完整链路其实由五个环节组成本地环境准备、SSH密钥生成与配置、远程仓库创建、本地项目初始化、首次推送。每个环节都有各自容易出问题的地方。比如很多人直接在Gitee网页上创建一个仓库然后本地执行git push结果提示权限不足或者推送被拒绝。这往往是因为前面的某个环节没做对——要么SSH密钥没有配置要么远程仓库里已经有了README文件导致本地历史和远程历史不兼容。把这个流程拆开理解的好处是当你遇到错误提示时你能迅速定位是网络问题、认证问题、还是分支冲突问题而不是漫无目的地搜一圈答案。1.2 为什么大多数教程会让你用SSH而不是HTTPS在配置远程仓库地址的时候Gitee提供两种协议HTTPS和SSH。我知道很多初学教程默认让你用HTTPS因为复制起来方便。但如果你打算长期维护一个项目SSH才是更省心的方案。HTTPS协议的仓库地址长这样https://gitee.com/用户名/仓库名.git每次push都需要输入Gitee的账号密码。虽然可以配置凭据缓存但一旦换了机器、换了终端环境又要重新登录。SSH协议地址是gitgitee.com:用户名/仓库名.git配置一次密钥之后后续push和pull都不需要再输密码。简单来说SSH就像是你给自己配了一把钥匙第一次把公钥放到Gitee服务器上以后每次访问都是自动认证。HTTPS则像是每次都要出示身份证用一次验证一次。长期使用SSH显然是更优的选择。2. 环境准备Git安装与SSH密钥配置实操2.1 Git安装——不同系统的安装方式在你做任何推送之前本地必须装好Git。Windows用户可以直接去Git官网下载安装包安装的时候一路点下一步就行。但有三个选项需要注意第一在“选择默认编辑器”这一步如果你不是Vim的忠实用户建议选Visual Studio Code或Notepad。否则以后提交代码时遇到冲突默认打开Vim会让新手不知所措。第二在“调整PATH环境变量”这一步选第二个选项“Git from the command line and also from 3rd-party software”。这个选项会把Git命令注册到全局PATH中保证你在任何终端工具里都能直接使用git命令。第三换行符转换方式默认选项“Checkout Windows-style, commit Unix-style line endings”就好后续如果跨平台协作再根据实际情况调整。Linux和macOS用户可以用系统自带的包管理器安装例如在Debian/Ubuntu上用apt install gitmacOS上如果没有Homebrew直接从Git官网下载安装包也行。安装完成之后在终端里执行git --version能显示出版本号就说明安装成功了。2.2 配置全局用户名和邮箱Git安装完成后第一步不是急着建仓库而是先告诉Git“你是谁”。这个身份信息会跟着每一次提交commit记录走别人在Gitee上看到你的提交记录时就会显示这个用户名和邮箱。打开终端执行git config --global user.name 你的名字 git config --global user.email 你的邮箱这里要注意邮箱不一定要用注册Gitee的那个邮箱建议用一个常用邮箱。因为GitHub、Gitee、GitLab这些平台都是通过邮箱来关联提交记录的。如果你用A邮箱提交却希望这些提交记录显示在B账号下平台就认不出来提交记录会变成一个独立的小人图标。配置好之后可以用git config --global --list查看所有全局配置确认无误再继续。2.3 生成SSH密钥并添加到Gitee这是整个流程里最容易被忽略、却又最重要的环节。我见过太多人在推送时报错Permission denied (publickey)归根结底就是SSH密钥没配对。生成密钥的方式很简单在终端执行ssh-keygen -t rsa -b 4096 -C 你的邮箱系统会让你选择密钥保存位置直接回车使用默认路径~/.ssh/id_rsa即可。接着会让你输入两遍密码短语passphrase这里可以直接回车跳过因为Gitee的SSH密钥本身就是认证凭证再加一道密码反而会在每次连接时多一次交互影响自动化操作的体验。执行完以后在你的用户目录下的.ssh文件夹里会生成两个文件id_rsa是私钥id_rsa.pub是公钥。私钥绝对不能泄露公钥是放到服务器上的。然后查看公钥内容cat ~/.ssh/id_rsa.pub把输出的内容完整复制。接着登录Gitee鼠标悬停在右上角头像处选择“设置”然后在左侧菜单找到“SSH公钥”把复制的内容粘贴进去标题随便填一个自己记得住的名称比如“laptop-home”最后点击确定。验证是否配置成功ssh -T gitgitee.com如果配置正确终端会显示一条欢迎语类似“Hi xxx! Youve successfully authenticated”后面还会跟着一些提示。我用的Gitee版本现在返回的欢迎语是英文的不影响判断只要看到successfully authenticated就稳了。3. 在Gitee上创建远程仓库3.1 新建仓库页面关键选项怎么填登录Gitee后点击右上角的“”号选择“新建仓库”进入创建页面。这个页面上的选项比较多但真正影响后续操作的核心选项只有三个仓库名称、仓库路径、分支模型。仓库名称建议用项目的英文名全小写单词之间用短横线连接。因为仓库路径默认会跟随仓库名称而仓库路径会成为你推送地址的一部分。如果你用了大写字母或空格推送地址可能不直观某些工具还会因为大小写问题产生莫名其妙的bug。初始化仓库这一栏如果本地已经有项目代码了那三个选项——README、.gitignore、开源许可证——都不要勾选。因为勾选任何一个Gitee都会在远程仓库自动生成一次初始提交导致本地仓库和远程仓库的历史不兼容首次推送就会报错failed to push some refs to。如果本地完全是空项目或者你想先让远程仓库有个基本骨架那可以勾选README和.gitignore。开源许可证这一项如果你不确定项目是否开源建议先选“无”。许可证是法律层面的东西选错了后续改起来很麻烦。分支模型这一项Gitee默认会选master。现在业界的新项目普遍用main作为默认分支名如果你希望保持一致可以在这里切换成main。本文后面的操作我按master来演示因为这是Gitee的默认值你只要注意本地分支名和远程分支名一致即可。3.2 仓库是私有还是公开再往下有一个“是否开源”的选项。私有仓库只有你自己和被你加入协作的成员能看到公开仓库则所有人都可以浏览和Cloning。如果你只是存放个人学习项目或者尚未成熟的代码建议选私有。以后想公开随时可以在仓库的“管理”页面改设置不用重新建仓库。创建完成后Gitee会跳转到仓库首页此时页面顶部会有一个仓库地址你可以用HTTPS和SSH两种方式查看。这里先记住SSH格式的地址因为这就是你后续推送要用的项目地址。3.3 仓库创建后第一件事复制SSH地址在仓库首页的右侧区域有一个“克隆/下载”按钮点击后会展开地址列表。选SSH那一栏复制完整的地址格式是gitgitee.com:你的用户名/仓库名.git。这个地址是远程仓库的唯一标识。后续你在本地执行git remote add origin 地址时用的就是它。如果复制错了版本比如复制成了HTTPS地址推送时就会要求输入账号密码又绕回HTTPS的老路了。4. 本地项目初始化与首次推送全流程4.1 从一个普通的项目文件夹开始现在假设你本地已经有一个项目文件夹里面是你的代码文件。打开终端进入这个目录。注意如果项目文件夹里存在庞大的依赖目录比如Node.js的node_modules、Java的target目录、IDE的.idea文件夹这些都不要提交到仓库。后面我们会用.gitignore统一处理但如果你现在就想直接执行git add .那还是在浪费时间。先执行git init这个命令会在当前目录下创建一个隐藏的.git文件夹意味着这个目录变成了一个Git仓库。这里有个细节所有版本控制信息都存在.git文件夹里如果你把这个文件夹删了项目的所有提交历史也就没了。接着你可以执行git status看看当前的变更情况会发现所有文件都处于“未跟踪”Untracked状态。在第一次提交之前我们需要把这些文件加入暂存区。4.2 写一份合格的.gitignore.gitignore是一个让Git忽略特定文件或文件夹的配置文件。我见过不少新手项目把node_modules整个推到仓库里代码没多少依赖几十兆拉下来慢不说还特别容易被判定为仓库体积过大。写.gitignore并不复杂只需要把你不想提交的内容路径写在里面。例如node_modules/ dist/ target/ .idea/ *.log .DS_Store每一行代表一条忽略规则。目录后面加/表示忽略整个目录*是通配符。具体规则可以根据项目类型补充GitHub上有一个专门的仓库维护各类语言的.gitignore模板Gitee的仓库创建页面也可以直接勾选生成一份基础的。4.3 完成第一批提交暂存区staging area是一个有意思的设计它让你可以把文件分成几批提交。对于首次提交通常直接添加所有文件git add .add只是把文件加入暂存区还没有真正保存到历史记录。接着执行git commit -m 项目初始化-m后面跟的是本次提交的说明信息。这个信息会在Gitee仓库的提交历史里显示建议写清楚这次提交的目的方便以后回溯。一个常见习惯是“动词对象”比如“init project”、“add user module”、“fix login bug”比“修改了一些东西”要有用得多。执行完commit后本地的提交历史就产生了。执行git log --oneline可以看到一条提交记录那是一个由哈希算法生成的字符串这就是Git管理版本的基石。4.4 关联远程仓库并推送本地仓库有了第一个提交接下来就是把它推送到Gitee。首先要告诉本地仓库远程地址是什么git remote add origin gitgitee.com:你的用户名/仓库名.git这里的origin是一个别名指代后面那一长串地址。以后推送、拉取都用这个别名不用重复输入完整地址。然后执行推送git push -u origin master-u参数的作用是把本地master分支和远程master分支关联起来。后续你在本地执行git push或git pull时Git会自动知道该往哪个远程分支推送或拉取不需要再指定一次。如果没有遇到任何报错终端会显示一个进度条最后提示master - master之类的信息表示推送成功。此时刷新Gitee仓库页面就能看到你刚刚提交的代码了。5. 日常使用中的高频操作与避坑技巧5.1 后续怎么再次推送首次推送成功以后日常开发就会形成一条标准流程修改代码 →git add .→git commit -m 描述→git push。这里有个小习惯我强烈推荐执行git commit之前先git status看一眼暂存区内容是否符合预期。因为git add .会把所有变更加入暂存区包括你无意间修改的文件。如果某个文件不该出现在这次提交里先git reset 文件名把它移出暂存区。推送时如果提示“Everything up-to-date”意思是本地和远程没有差异不需要推送。这通常是因为你忘了commit只执行了add。记住add只是把变更放进暂存区commit才是真正创建了一条提交记录而push是把提交记录传到服务器三者缺一不可。5.2 推送被拒绝怎么办这是我最常被问到的问题之一。当远程仓库和本地仓库历史不一致时推送会被拒绝典型错误是non-fast-forward或者failed to push some refs to。这种情况一般发生在远程仓库里有你本地没有的提交。比如你在Gitee网页上先勾选了README初始化又或者在Gitee网页端直接修改过某个文件而本地commit的基准还是旧状态。解决方法有两种。第一种比较直观先把远程新的提交拉取下来合并后再推送。git pull origin master如果提示需要设置关联分支就补上--set-upstream参数git pull --set-upstream origin master拉取完成后Git可能会打开一个合并提交的信息编辑界面不用慌默认保存退出就行。然后再执行git push一般就能成功了。第二种情况是两边代码冲突较大直接合并会产生一堆冲突标记。如果你确定本地的代码是最新的远程的初始提交没有保留价值可以直接用强制推送git push -f origin master但这条命令要慎重因为它会覆盖远程仓库的历史。在你自己一个人的仓库里用没问题但如果仓库里有其他协作者强制推送可能会丢掉别人提交的记录。5.3 如何修改提交信息git commit --amend如果你的commit信息写错了比如错别字、或者描述不准确在推送之前可以将最后一次提交的信息重新修改git commit --amend -m 正确的提交信息--amend的意思是将当前暂存区的内容和上一条提交合并成一个新的提交。如果你只是修改信息不需要add任何东西。但要注意这个操作会改变提交的哈希值如果这条提交已经推送到了远程最好不要再amend否则协作方拉取时会发现历史对不上。5.4 分支名称不同对推送的影响Gitee默认初始化的远程仓库分支是master但如果你在创建仓库时把默认分支切成了main而本地初始化的分支默认还是master那么执行git push origin master时会提示找不到远程分支或者在git pull时出现分支跟踪混乱。解决这个问题最简单的方式是在本地把分支重命名git branch -M main-M会强制重命名当前分支为main然后再执行git push -u origin main本地分支名不需要和远程一致吗不一定。理论上Git允许你推送任意本地分支到任意远程分支但日常开发建议保持一致不然你每次都要写完整的推送命令还容易看混。6. 常见问题速查表与配套工具6.1 高频问题与解决方案问题现象原因分析解决方案Permission denied (publickey)SSH密钥未添加或添加错误重新生成密钥并把id_rsa.pub内容完整复制到Gitee的SSH公钥设置里Project not found仓库地址中的用户名或仓库名拼写错误复制仓库首页的SSH地址不要手动输入Repository not found私有仓库且未添加本人关联确认当前登录的就是该仓库所属账号failed to push some refs to远程有本地没有的提交先git pull origin master合并后再执行git push每次push都要求输密码使用了HTTPS仓库地址更换为SSH地址git remote set-url origin gitgitee.com:用户名/仓库名.git文件超过Gitee大小限制单文件超过100MB将大文件移除出仓库或使用Git LFS管理提交记录里显示的不是自己的头像提交邮箱没有关联Gitee账号在Gitee设置里添加该邮箱或重新配置user.email6.2 通过IDE和图形工具操作Gitee如果你用的是IntelliJ IDEA这样的IDE可以在Settings里的Version Control菜单中找到Git配置把Gitee集成进去。IDEA左侧的Git窗口可以直接看到提交历史、暂存区、分支关系推送和拉取都有图形化按钮。如果要用TortoiseGit这类Windows图形工具拉取Gitee仓库方法也很简单安装TortoiseGit之后在本地右键选择“Git Clone”把仓库的SSH地址粘贴进URL一栏点击确定就会自动拉取。如果提示找不到密钥文件记得在TortoiseGit的设置里指定C:\Users\你的用户名\.ssh\id_rsa这个路径。我在实际使用中发现图形工具和命令行并不冲突。日常看个commit记录用图形界面更直观但遇到合并冲突或者复杂分支操作命令行反而更好控制。建议两套手段都掌握遇到问题时不至于卡住。6.3 推送之后的进一步扩展Gitee Pages代码推送到Gitee之后如果你做的是静态站点可以直接借助Gitee Pages部署成网页。仓库页面的“服务”菜单里能找到Gitee Pages选项首次使用需要先实名认证然后选择部署的分支和目录Gitee会自动构建并生成一个访问地址。我试过把个人博客搭在Gitee Pages上自己写文章、本地build、推送、自动更新整个流程非常顺滑。它不需要额外服务器也基本不用运维适合把演示页面、项目文档、简历主页这类东西放上去。唯一要注意的是部署目录如果选择了/docs你需要保证项目推送时这个目录已经被构建出来了。6.4 团队协作时如何避免互相覆盖当多个人同时往同一个仓库推送代码时建议约定好分支管理策略。最简单的一种做法是每个成员在自己的分支上开发完成后合并到主干。操作流程是git checkout -b feature-login # 写代码、提交 git push -u origin feature-login然后在Gitee仓库页面发起一个Pull RequestPR由项目负责人审核后合并。这种流程能减少直接往主干上乱推带来的冲突风险。即便是个人项目我也建议保留主干分支的整洁性每次修复或新功能都开一个独立分支合并后再删除历史记录会清晰很多。7. 我实际工作中保存下来的一些体会文章写到最后分享几个我自己最初学Git时踩过的坑这些几乎是每个新手都会遇到的问题。第一个坑是把敏感信息提交上去了。数据库连接密码、云服务器的密钥等一旦被推到远程仓库即使后来删掉文件也仍然留在Git提交历史里。对私有仓库来说风险没那么高但如果是公开仓库任何人clone下来都能顺手翻到。所以提交之前一定要检查暂存区的文件.gitignore里把配置类文件排除掉比如原有的application.properties不提交只提交application.example.properties这种模板文件。第二个坑是提交信息写得太随意。一年之后回看项目的提交历史如果每一条都是“update”或者“fix”你根本分不清这些提交到底干了什么。我现在写提交信息会刻意遵循“这个改动解决了什么问题”的思路比如“修复订单列表在弱网环境下加载不出的问题”而不是“修复bug”。这看起来是小事但维护开源项目或者过段时间再接手自己的项目时价值就出来了。第三个坑是依赖了图形工具不会用命令行。功能越多的图形界面对新手越友好但一旦离开那个环境就寸步难行。我在本地开发环境很少用GUI基本都是终端敲命令行对我理解Git原理帮助很大。但我也理解很多人更喜欢图形化的操作方式这个没有对错最终目标都是把代码安全、稳定地管理起来。创建Gitee仓库并推送项目核心就三件事本地Git环境配好、SSH密钥对上、分支历史同步好。这套流程跑通一次后面所有操作都是在这条主线上重复。如果你在实操中遇到前面表格里没覆盖到的报错把错误提示完整复制到搜索引擎里搜一遍同时查看本地分支和远程分支的状态大多数问题都能自己定位出来。