没接触过代码托管的人可能觉得“Gitee”离自己很远可真正开始写代码、存项目、跟别人协作之后才发现这个东西几乎每天都在用。这篇2021年最新Gitee使用教程不讲虚的从注册、建仓库、推送代码一直到分支管理、Pull Request、Pages部署和避坑全部按实际操作顺序捋一遍。我在各种团队里折腾过不少代码托管方案最后日常主力还是放在Gitee上速度快、国内访问顺手、功能也够全。这篇文章适合刚接触Git的新手也适合那些用过GitHub但想切换或者增加一个国内仓库来用的开发者按着步骤走基本不会卡住。代码这东西最怕的是“跑在自己电脑里别人拿不到”。早些年见过不少同事项目做到一半用U盘拷贝、用网盘传压缩包或者干脆把整个文件夹丢到微信传输助手里。版本一多全是什么“final最终版”“final2打死不改版”最后哪个是真的都分不清。后来大家慢慢统一用Git做版本管理、用代码托管平台做集中存储这个问题才算解决。Gitee作为国内使用率很高的代码托管平台解决了Git仓库的存放、分享、协作、展示这一条完整链路而且对中文用户非常友好。1. 为什么选择Gitee场景、优势与方案选型1.1 代码托管解决了什么问题往大了说代码托管平台做的是三件事存代码、管版本、促协作。存代码不只是备份到云端那么简单而是让团队里每个人都能拿到同一份最新代码管版本是指每一次改动都有记录想回滚随时回滚促协作则是让多人并行开发时不会因为谁先改谁后改而出乱子。用生活里的事情来类比Git就像咱们写文档时的“修订模式”只不过它管的不是一段话而是整个项目目录。每一次提交commit都相当于给项目拍了一张快照附带上谁拍的、什么时候拍的、拍的内容是什么。Gitee在Git之上加了一层网页操作界面把仓库可视化、把分支展示出来、把合并请求变成审批流程这就让非命令行爱好者也能很自然地用起来。1.2 和自建平台、其他托管的取舍团队里有人喜欢什么都不依赖、自己搭一套Git服务器用命令行的方式管理。自建方案的好处是数据完全在自己手里、可以无限私有化但坑也明显服务器维护、磁盘备份、账号体系、权限管理、Web端体验全都得自己操心小团队搭一次能跑长期维护是真费精力。相比之下托管平台把这些问题都接走了注册个账号就能用。另外很多开发者以前主力用的是海外平台偶尔会遇到访问速度不理想、页面加载慢、推送大一点的项目要等很久这类问题。Gitee是国内平台日常访问、推送、拉取的体验会顺畅很多而且和开源中国的产品生态有联动中文界面、中文文档、中文社区对初学者极其友好。我个人的选型原则是个人项目和团队协作项目优先放Gitee需要跟海外协作时就做双向同步两边各留一份互不耽误。1.3 Gitee适合哪些人用基本上写代码的人都适合。单机开发者可以把Gitee当作免费网盘加备份工具所有项目集中管理学校里的学生可以用它创建私有仓库存放课程设计、毕业设计还能用Pages功能部署个人主页开源项目爱好者可以通过Fork和Pull Request参与别人的项目企业团队则可以用它做内部代码管理、需求跟踪和代码审查。我自己见过不少非技术背景的朋友因为要发个小程序demo或者部署个人简历页也开始用Gitee门槛确实不高。2. 注册登录与创建第一个仓库2021新版界面操作全流程2.1 注册账号与基本设置进入Gitee官网右上角就是注册入口。注册时可以用手机号也可以直接用第三方账号授权登录基本就是填手机号、收验证码、设密码这几步一两分钟就搞定。建议注册完顺手把头像、个人主页、常用邮箱这些信息补全因为后面提交代码时Git会把用户名和邮箱写到提交记录里其他协作者就是通过这些信息认出你是谁的。这里有个小细节提交代码时显示的名字跟你Gitee账号的昵称没有必然关系真正起作用的是本地Git配置里的user.name和user.email。所以注册完之后的第一件事是把本地Git的全局身份信息设置好否则后面提交记录里的名字可能乱掉。命令是这样git config --global user.name 你的昵称 git config --global user.email 你的邮箱我在实际协作过程中有过不止一次因为邮箱写错、导致提交记录归不到人头上的情况所以强烈建议第一步就配好别等推送完再返工。2.2 创建仓库的完整路径登录之后点击右上角的“”号选择“新建仓库”或者直接进仓库列表页点“新建仓库”按钮。进入创建页面后需要填几项关键信息仓库名称这个是必填项只能包含字母、数字、下划线、中划线等常见字符建议起一个能一眼看出项目用途的名字比如blog-source、mall-server。路径通常和仓库名自动绑定但可以手动改实际访问URL里看到的就是这个路径。描述可以简单写一下这个项目是干什么的方便别人在看仓库列表时快速了解。私有/公开公开仓库所有人都能看到适合开源和分享私有仓库只有你自己和被你授权的协作者可见。敏感项目、未完成的作品建议先设私有发布时再调成公开。初始化仓库可以勾选“使用Readme文件初始化这个仓库”也可以先选.gitignore模板。我个人的习惯是如果不确定要不要放Readme就先勾上因为后面推送时可以减少一次“空仓库”的边界问题。创建完成后页面会跳转到仓库主页能看到仓库地址包括HTTPS地址和SSH地址。这一步做完远程仓库就有了接下来要在本地把它用好。2.3 本地安装Git与环境检查Windows环境下去Git官网下载安装包一路默认安装就行。macOS一般自带Git不过版本可能偏老如果遇到问题可以用包管理器装新版。Linux发行版更简单通过自带的包管理器安装即可。装完之后打开终端Windows下用Git Bash或者PowerShellmacOS/Linux直接开终端先确认一下版本git --version能看到版本号就说明装好了。这一步没什么技术含量但很多人会在“编辑器里能用Git命令吗”这个问题上纠结。其实没必要编辑器里的图形化操作底层调用的还是Git命令命令行掌握一遍以后不管用哪个IDE都会很有底气。3. 本地初始化与推送代码从零到第一个远程提交3.1 初始化本地仓库并完成首次提交假设你已经在本地有一个项目文件夹里面放着代码、文档、配置文件。终端里进入这个目录然后执行git init这条命令会在当前目录下创建一个隐藏的.git文件夹这个文件夹是Git用来记录版本信息的核心目录不要手动去动它。执行完git init之后仓库还处于“什么都被跟踪”之前的状态需要先加文件再提交git add . git commit -m 第一次提交git add .代表把当前目录下所有文件都加入暂存区git commit把暂存区的内容打包成一个版本快照后面-m后面的内容就是本次提交说明。从这一刻起项目就有了第一个版本记录。关于提交说明我的经验是别写“改了点东西”“更新一下”这种等于没说的话。理想情况是让人不看代码也知道这次改了什么、为什么改。比如“修复登录接口在空密码时返回500的问题”“优化首页图片懒加载逻辑”这类说明在翻历史记录时会非常省力。3.2 关联远程仓库的HTTPS方式本地仓库准备好之后要把代码推送到Gitee上。在仓库主页找“克隆/下载”按钮复制HTTPS地址然后在本地终端执行git remote add origin https://gitee.com/你的用户名/你的仓库名.git git push -u origin master这条命令把本地分支master推送到远程仓库的master分支-u参数的意思是建立本地分支与远程分支的跟踪关系。推送过程中HTTPS方式会要求输入Gitee的用户名和密码输入一次后很多客户端会帮你记住有些场景下每次都要输入后面我会在常见问题里讲怎么处理。HTTPS方式是入门最友好的方式因为它不需要额外生成密钥只要账号密码就能推适合临时用。但对于频繁推送的开发场景每次都输密码确实影响效率所以更推荐SSH方式。3.3 SSH密钥的配置与免密原理SSH方式的核心逻辑是“本地生成一对密钥公钥放到Gitee私钥自己保管”。推送的时候Gitee通过公钥识别出“这确实是你的电脑”于是就不再要求输入账号密码了。生成密钥的命令ssh-keygen -t rsa -b 4096 -C 你的邮箱执行过程中会提示设置密钥文件的路径和口令直接回车用默认路径~/.ssh/id_rsa即可。如果之前生成过密钥它会提示是否覆盖要小心操作别把旧密钥弄丢了。生成完成后查看公钥内容cat ~/.ssh/id_rsa.pub复制整段内容回到Gitee进入“设置”里的“安全设置”找到“SSH公钥”把内容粘贴进去起个便于识别的标题保存。之后在本地把远程地址改成SSH格式git remote set-url origin gitgitee.com:你的用户名/你的仓库名.git再执行推送会发现不用输密码了。这套配置我只花了几分钟但之后一年省下了无数次输密码的时间属于典型的一次配置长期受益。3.4 推送时的常见状态与命令解析第一次推送时如果远程已经有Readme文件而本地仓库还没有很容易出现推送被拒的情况。因为两边仓库的历史记录不一致Git出于安全考虑会拒绝合并。解决方法是先把远程内容拉下来再推送git pull origin master --rebase--rebase的作用是把本地的新提交变基到远程提交之上形成一条更线性的历史。很多人第一次遇到“failed to push some refs”就慌其实核心原因就是这么简单远程有本地没有的提交先同步就完事了。日常推送还有一个高频操作就是修改完代码后提交-推送循环。建议养成一个习惯提交前先用git status看变更状态用git diff检查具体改了哪些内容确认无误后再git add和commit。这能有效防止把调试代码、临时文件、敏感配置误提交上去。4. 分支管理、Pull Request与多人协作团队开发的核心玩法4.1 分支的概念与基本操作分支是Git最值得花时间去理解的概念。一个仓库可以同时存在多个分支每个分支相当于一个独立的工作副本。默认分支一般叫master或main你可以从它上面切出另外一个分支来开发新功能git checkout -b feature/login这个命令会创建并切换到一个名为feature/login的新分支。在这个分支上的所有提交都不会影响原来的master分支。等开发完成并测试通过后再把feature/login合并回master。分支的好处在于“隔离”。团队多人同时开发时A改登录模块、B改支付模块各开各的分支互不干扰。如果所有人挤在同一个分支上开发经常出现“我还没写完的代码被别人拉下来运行出错”的尴尬场景有了分支这种事就基本避免了。合并分支的命令git checkout master git merge feature/login如果合并过程中发生冲突Git会在冲突文件里标出两边不同的内容手动修改后再提交即可。第一次遇到冲突可能会觉得麻烦但多来几次就会发现这其实是Git在帮你保留双方的工作成果比直接互相覆盖要安全得多。4.2 Fork Pull Request参与开源项目Gitee上有大量开源项目想参与贡献不需要直接向项目仓库提交代码而是先Fork一份到自己的账号名下然后在自己这个副本上修改最后向原仓库发起Pull Request简称PR。流程是这样的打开感兴趣的开源项目仓库点Fork按钮原仓库的代码会复制一份到你的账号下。把你自己账号下的仓库克隆到本地新开一个分支进行开发。开发完成后推送分支到你的远程仓库。在原项目仓库页面点击“新建Pull Request”把目标分支设为原仓库的目标分支来源分支设为你刚才推送的分支。填写PR说明提交后等待项目维护者审查、评论、提出修改意见。这个流程看起来简单但里面藏着一些潜在的坑。比如Fork之后原仓库可能一直在更新你的本地副本会逐渐落后所以开始开发前建议先把原仓库的新提交同步到你自己的仓库。Gitee提供了“同步”按钮按一下就能拉取上游更新非常方便。另外PR的说明是关键。写清楚你改动了什么、为什么这么改、怎么测试的、是否涉及破坏性变更这些信息能极大降低维护者的审查成本。我在参与一些项目时看到连PR模板都不填、只丢一行“更新代码”的情况第一反应通常不会想去合并。4.3 Issue、里程碑与团队任务协作代码托管平台不只是存代码的地方也是项目管理的载体。团队里可以拿Issue来跟踪任务有Bug就提Bug Issue有新需求就提功能Issue通过标签分类bug、enhancement、help wanted等通过里程碑把多个Issue归到一个版本目标下。实际工作中我的习惯是每接到一个任务先在Gitee上创建一个Issue描述背景、验收标准、负责人然后从这个Issue出发拉一个分支分支名里带上Issue编号。比如fix-123-login-timeout这样从分支名就能看出对应哪个任务。完成之后在PR描述里写上“修复 #123”PR合并时Issue会被自动关联项目进度一目了然。这套流程不需要额外引入复杂的项目管理工具只要团队养成习惯一个仓库就能把代码和任务串起来。对于中小团队来说性价比非常高。4.4 代码审查与保护分支Gitee支持在合并PR时设置审查规则比如必须至少一位审查人通过才能合并、合并前要求CI通过等。这些规则能有效防止“代码直接推到主干、质量没人把关”的情况。设置保护分支时通常做法是把master或main设为保护分支普通成员不能直接推送改动必须通过PR提交由指定审查人确认后再合并。这样一来主干分支的每一次更新都有记录、有审批、可回溯。我见过一些团队刚开始不愿意走PR流程觉得流程重、速度慢。但项目到一定规模代码质量问题和协作冲突的出现概率大幅上升一套强制审查机制能提前拦截掉很多低级问题。等到出了问题再补流程成本和阻力都比从一开始就养成习惯大得多。5. Gitee特色功能Pages部署、WebHook、代码片段与项目统计5.1 用Gitee Pages部署静态网站和个人主页Gitee最吸引我的一点是内置了Pages服务可以把静态网站直接托管在Gitee上。个人主页、项目文档站、纯前端的Demo预览都能一键部署省去了自己买服务器、配Nginx的麻烦。使用方式很简单在仓库里放好静态文件比如index.html、CSS、JS进入仓库的“服务”或“Pages”页面选择部署分支和部署目录点击启动稍等片刻就能拿到一个公网访问地址。后续每次推送更新到对应分支Pages都能自动触发更新。如果你会使用静态站点生成器比如Hexo、Hugo这类工具配合Gitee Pages就能搭出一个个人博客。我之前帮A同学搭建个人简历页用的就是Gitee仓库加一个纯HTML页面半小时就上线了。关于Pages有个细节要留意官方要求绑定的域名和仓库要先做校验如果要使用自定义域名需要按平台的CNAME配置要求去解析。首次配置时可能因为域名解析生效有延迟而提示不通过等一段时间再刷新就好。5.2 WebHook与自动化触发WebHook是Gitee提供给开发者的一把“联动钥匙”。简单说就是当仓库发生特定事件比如push、PR、Issue变更时Gitee会向你所填写的URL发送一个HTTP请求通知你的服务器去执行后续操作。最常见的场景是自动部署线上服务器上跑一个部署脚本接收WebHook通知后自动拉取最新代码、执行构建、重启服务。这样开发者只需要推送代码部署的活儿交给自动化完成。配置WebHook时要注意的点是回调地址要能被公网访问到而且Gitee会附带签名信息服务端应该校验来源避免随便哪个请求都触发部署。这个功能对个人开发者可能用不到但对需要频繁发版的小团队来说能省下大量手动操作的时间。5.3 代码片段与速查笔记Gitee提供了代码片段Snippet功能适合存放一些零散但常用的代码块比如某个函数的实现、某条正则表达式、某个指令的用法。和仓库不同代码片段不需要完整的项目结构创建一个片段、写一段说明、附上代码就能保存和分享。我平时的习惯是把工作中常用但容易忘的代码块整理成代码片段比如统一返回格式的工具函数、日期格式化函数、部署脚本模板。等下次换个项目写OpenAPI接口时直接打开片段复制比去旧项目里翻代码要快得多。代码片段还可以设置语言高亮和可见范围私密片段当个人笔记用也很好用。5.4 仓库数据统计与徽章Gitee仓库页面上会显示提交数、分支数、发行版、贡献者等信息。团队复盘时可以看趋势图了解最近一段时间的代码活跃度。这对个人开发者来说也是种记录看到自己的提交热力图越来越密会有一种实实在在的成就感。另外如果想在Readme里展示一些状态徽章Gitee也提供了若干内置徽章比如仓库状态、许可证、代码质量等。这类小细节看起来不起眼但在开源项目落地页里能增加不少专业感。对简历和个人主页这类对外展示的场景作用会更加明显。6. 常见问题与排查技巧实录推不上去、免密失效、误删文件怎么办6.1 推送被拒提示“failed to push some refs”这个问题我遇到太多次了。出现的原因基本就是远程仓库有本地没有的提交而本地也有远程没有的提交Git不知道以谁为准拒绝盲推。解决办法是先同步git pull origin master --rebase然后再push。这里有个要注意的细节多人协作时自己在功能分支上开发了很久合并master时冲突可能不少。建议每开发一段时间就定期把最新的master合并进自己的分支别等到最后一天再一次性合并那样冲突会堆到一起改起来非常痛苦。6.2 HTPS方式每次都要输密码如何免密如果是HTTPS方式密码输一次两次还行每次都输就很烦。解决办法主要有两种一种是改用SSH方式就是前面讲的生成密钥并配置公钥然后git remote set-url把远程地址换成SSH格式。这种方式是官方推荐也是最彻底的办法。另一种是配置Git凭据存储。在Windows下可以执行git config --global credential.helper store这样第一次输完密码后Git会把它明文存到用户目录下的.git-credentials文件里后续不再询问。这种方式方便但安全性弱一些适合个人电脑使用。公司或公共电脑不建议开启因为密钥文件相当于把账号密码都交出去了。6.3 不小心提交了不该提交的文件怎么撤销这是新手最恐慌的场景之一。如果只是本地提交还没推送可以用git reset --soft HEAD~1这个命令会撤销最近一次提交但保留文件改动在暂存区。如果想改得更彻底把文件从Git中移除但保留在本地工作区git rm --cached config.yaml如果已经推送到远程仓库事情分两种如果错误提交的内容是普通代码文件用git revert生成一个新的反提交来抵消它这种属于安全操作适合协作分支如果提交的是密码、密钥这类敏感信息光revert还不够因为历史里还残留着那份内容正确做法是立即改密码、撤销密钥并考虑是否要借助git filter-branch或相关历史改写工具清理。我在这个点上栽过跟头有一回不小心把接口密钥提交到了公开仓库发现后虽然立刻删了并重新提交但密钥其实已经在历史里暴露了最后被迫换了一套新密钥。从那之后我养成了两个习惯一个是提交前一定用git status和git diff确认内容另一个是给公开仓库安装一个文件内容检查的钩子凡是匹配到密钥关键字的都不允许提交。6.4 多个Gitee账号在同一台电脑上如何切换很多人会拿公司账号和个人账号在同一台电脑上使用SSH密钥只有一个时访问其中一个就会出现权限问题。解决办法是配置多个SSH密钥并在~/.ssh/config里做区分。大致思路是为每个账号生成独立密钥文件比如id_rsa_work和id_rsa_personal然后把各自的公钥分别配置到对应Gitee账号下再把不同的Host别名映射到不同密钥上。之后在克隆仓库时把远程地址里的gitee.com替换成给你的别名就能实现自动选用对应密钥的效果。这个配置要稍微折腾一下但弄好之后两个账号在同一台电脑上互不干扰。我见过有同事图省事两个账号共用同一个邮箱和用户名去做推送导致服务端把提交记录归错人最后开Review时说不清哪段代码是谁写的所以这部分还是值得花时间一次解决。6.5 文件名大小写、换行符与中文路径的坑跨平台协作中最容易出的问题之一是文件名大小写。Windows和macOS默认不区分大小写Linux区分而Git在部分场景下记录文件名大小写。比如在Windows上把Readme.md改名成readme.mdGit可能完全没感知到推上去之后Linux环境里就会出现文件找不到的问题。解决方案是修改Git的大小写敏感配置git config core.ignorecase false修改后如果文件确实需要重命名先git mv再提交。换行符也是一个隐藏坑。Windows下文件保存时行尾是CRLFLinux和macOS默认是LF如果团队里两个系统混用Git容易提示“整个文件都变了”。业内通用做法是统一换行符策略在项目根目录放一个.gitattributes文件声明* textauto eollf让Git在提交时自动统一转换避免提交记录里出现无意义的满屏diff。关于中文路径Gitee本身是支持中文仓库名和文件名的但个别Git客户端处理中文路径偶尔有显示乱码的问题。我的建议是仓库名尽量用英文这里的英文不只是为了兼容工具也是为了让协作方的本地环境少遇到一些不可控的问题。6.6 大文件导致推送失败Git仓库在存储设计上适合文本文件不适合二进制大文件。把几百兆的视频、压缩包直接提交进仓库会让仓库体积膨胀每次克隆和拉取都非常慢甚至直接推送失败。Gitee仓库本身也有体积限制如果项目里有非用不可的大文件正确方案是使用Git LFSLarge File Storage将大文件指针存入仓库实际内容存到LFS服务器。在项目根目录执行git lfs install git lfs track *.mp4 git add .gitattributes之后再提交文件就自动走LFS通道了。这里要特别提醒LFS必须在提交大文件之前就配置好而不是等推不上去再去配因为Git已经把大文件对象写进本地仓库了后续清理很麻烦。写到最后的一点个人体会用Gitee这么久最大的收获倒不是某个功能有多好用而是习惯了“一切有记录、所有可回溯”的做事方式。代码写错了不可怕历史记录里总有可以回退的地方功能乱了也不可怕分支切走之后再慢慢修就行。这种安全感是代码托管平台带给我最实用的一份价值。如果你还在用压缩包管理代码真的建议从今天开始建一个仓库、推一次提交试过一次之后大概率就回不去了。后面再一步步把分支、PR、自动化这些都用起来整个开发节奏会变得顺畅很多。