★ FEATURED ARTICLE 做开发这些年Git基本是每天必碰的工具代码托管平台的选择直接影响协作效率。2021年我重新整理了一版Gitee使用教程正好赶上平台在这段时间功能调整比较多、也真正跑成熟的阶段。Gitee是国内的Git代码托管平台注册流程、界面文案、访问速度都更贴近国内开发者的真实使用习惯对于刚开始接触Git的人或者想把团队协作流程稳定下来的场景都是一个很合适的起点。很多新人第一步容易卡在“我应该选哪个平台”。如果你做的是完全开源、面向国际社区的项目海外平台自然有它的优势但如果你在准备学校课程作业、管理企业内部项目或者只是想把自己的练习代码、笔记、文档妥善托管起来Gitee的价值非常明确仓库在国内服务器上日常clone、push、pull这些操作速度稳定不太会出现让人干等的局面。免费账号就能创建私有仓库不必为了藏一份半成品代码去折腾额外配置。中文界面和引导资料对新手友好短时间内能搞清楚“分支”“合并”“Pull Request”到底怎么操作。通知提醒和国内常用办公工具的贴合度更高代码动态能第一时间同步给相关人。另一个容易被忽略的优点是教学场景的支持。不少高校的课程设计、毕业设计直接要求用Gitee交付老师可以方便地建组织、看提交历史、对分支做评审。换句话说就算你刚接触Git不久Gitee的学习曲线也不会陡到哪里去。本文提到的功能以2021年前后的Gitee版本界面为准平台后续在页面布局上会有小调整但核心流程和思路是通用的。1. 为什么2021年我依然把Gitee作为首选托管平台聊教程之前先说说选型。很多人觉得Git托管平台都差不多随便选一个就行实际用下来差异还是不小。我个人选Gitee出发点不是“国产替代”这种宏大理由而是实实在在的体验优势。1.1 本地化体验速度、语言、协作链路首先是速度。代码托管这件事最影响心情的就是push和pull的耗时。Gitee的服务器部署在国内日常操作基本不会因为跨国网络链路而卡顿在2021年这个时间点这一点对国内开发者来说几乎是刚需。凡是经历过几MB的仓库慢慢推送的人都会明白什么叫“白白消耗注意力”。其次是语言和文档。Gitee的中文界面把Git里的概念翻译得很直白比如“拉取请求”“分支管理”“代码审查”新手看面板就能猜个七八分。不是说英文界面不行而是刚接触Git时双线学习“Git命令英语术语”确实劝退过很多人。用中文界面至少能把精力先集中在理解工作流本身。然后是协作链路。Gitee的Issue、PR、看板、里程碑这些功能都内置在同一个平台里不需要额外去对接多个工具。小团队从创建仓库到分配任务再到代码评审全程在一个网站内完成这对团队协作效率的提升非常明显。你不需要让每个人都去学习一套新的项目管理工具学习成本低落地速度就快。1.2 免费私有库被低估的价值在2021年Gitee免费用户就可以创建私有仓库。这件事的价值被很多人低估了。不少人觉得私有库没什么用但实际开发中课程设计、公司内部工具、个人笔记、配置备份都未必适合公开。免费私有库意味着你可以把大量“不太见得人”的代码也纳入版本管理而不是让它们在硬盘里裸奔。我见过太多人的代码只存在本地没有备份不做版本管理。一旦硬盘坏了、文件被误删几年的积累就没了。有了免费私有仓库你可以把任何阶段的代码都推上去不用有心理负担。公共仓库让人慎重的点是“所有人都能看到”私有仓库能让人养成“随时提交、随时备份”的好习惯这个习惯对开发者来说是受益终身的。2. 从注册到第一个仓库30分钟跑通全流程2.1 注册环节的两件小事打开Gitee官网注册流程很简单手机号验证、设置用户名和密码。这里有一个容易被忽视的细节用户名不要随便填因为它会直接出现在仓库地址里类似gitee.com/你的用户名/仓库名。如果你之后想改用户名平台虽然支持但旧地址会失效别人克隆的仓库、文档里记录的链接都要跟着更新非常麻烦。邮箱建议填一个长期使用、不轻易更换的。如果你对公开信息比较敏感可以在个人设置里找到邮箱展示的相关选项隐藏真实邮箱或者使用平台生成的邮箱别名。这样后续提交记录里不会直接暴露你的真实联系方式又不会影响Git识别提交者身份。提示用户名、邮箱、SSH Key这三样注册时花10分钟一次配置好能省掉后面不知道多少核对信息的功夫。2.2 创建仓库时的参数到底该怎么选登录后点击右上角“新建仓库”界面会要求填写仓库名称、介绍、初始化选项、许可证等。大部分场景下仓库名称建议全小写英文单词之间用短横线连接比如blog-demo、course-design。名称里尽量避免中文、空格和特殊符号否则在命令行操作时容易遇到转义问题。初始化选项里有几个勾选项README、.gitignore、开源许可证。我的建议是新项目一定勾上README。README不只是给别人看的更是给你自己看的时间久了很容易忘记项目当初要解决什么问题。.gitignore 根据项目的语言框架选择对应模板即可比如Java项目选Java模板Node项目选Node模板这样一开始就能把构建产物和临时文件排除在外。许可证则取决于你有没有开源计划纯练习项目可以暂时不选以后需要再补。仓库的公开还是私有免费用户就可以创建私有仓库。个人笔记、配置模板、半成品项目都建议选私有等真正想对外开放了再到仓库设置里改为公开。从私有改公开容易从公开改私有反而要考虑历史遗留问题所以宁可先保守一点。2.3 SSH Key配置一次配好长期免密很多初学者习惯用HTTPS方式clone和push也能用但每次push都要输入账号密码用久了非常烦躁。更推荐的做法是配置SSH Key。配好之后本地电脑与Gitee之间的传输走SSH协议不需要反复输密码。生成密钥的命令Mac和Linux直接在终端执行Windows建议用Git Bashssh-keygen -t ed25519 -C 你的常用邮箱命令执行后一路回车即可默认会在用户目录的.ssh文件夹下生成一对密钥文件。如果你的系统环境比较老部分工具链还兼容不了ed25519也可以退回RSAssh-keygen -t rsa -b 4096 -C 你的常用邮箱接着查看公钥内容cat ~/.ssh/id_ed25519.pub复制输出的内容打开Gitee的“个人设置→安全设置→SSH公钥”粘贴保存。之后在终端测试ssh -T gitgitee.com看到欢迎提示就说明通了。这一步只有第一次配置时需要换电脑或换密钥才需要重新添加所以值得花几分钟配好。2.4 把第一个版本推送到Gitee仓库创建好后页面上会显示两套远程地址HTTPS和SSH。推荐复制SSH地址因为我们已经配置过SSH Key。在本地项目目录里执行git init git remote add origin 你的SSH地址 git add . git commit -m init project git push -u origin master-u参数的作用是建立本地分支与远程对应分支的关联。第一次推送必须带上之后在同一分支上直接git push就能推送到正确的远程分支。如果新仓库默认分支是main把最后一行替换成git push -u origin main即可。如果你不是从空仓库开始而是想直接拉取线上已有的仓库那就更简单git clone 你的仓库地址这样会直接得到一份完整的本地副本省去手动初始化仓库的步骤。3. 本地Git与Gitee协作日常开发最常用的命令流3.1 一套不会出错的标准工作流仓库建好只是开始日常开发真正打交道的是“本地修改→远端同步”这个循环。我建议小团队和个人开发都养成一个习惯不要在默认分支上直接写新功能而是每个功能开一个分支。假设你准备给项目增加一个“用户登录日志”功能标准流程是这样的git checkout master git pull git checkout -b feature/login-log接下来正常写代码完成后git add . git commit -m feat: 增加用户登录日志 git push origin feature/login-log等功能验证通过再回到主分支合并git checkout master git pull git merge feature/login-log git push origin master这样做的好处是每个功能的变更都隔离在自己的分支里不会干扰主分支的稳定性。就算新功能写了一半发现思路彻底走不通直接丢弃这个分支再开一个新的就行主分支永远保持可用状态。日常开发中还有一些高频操作可以对照速查场景命令说明拉取最新代码git pull等于fetch加merge创建并切换分支git checkout -b xxxxxx为分支名查看当前状态git status查看改动与未提交内容查看提交历史git log --oneline简洁显示历史撤销未提交改动git checkout -- 文件名恢复文件到最近一次提交合并某分支git merge xxx把xxx合并到当前分支删除本地分支git branch -d xxx只能删除已合并的分支3.2 Push被拒先拉代码再推送别硬刚初学者最容易遇到的报错是push被拒提示类似remote rejected或failed to push some refs。原因通常是远端分支已经领先于本地比如同事在你之前推送了新内容或者你在网页端直接改过文件。解决办法是先拉取远端更新到本地git pull如果本地和远端改的是同一个文件的不同部分Git有时能自动合并有时会提示冲突。冲突时用git status查看具体是哪些文件打开文件会看到类似 HEAD到的标记。把需要的代码保留删掉冲突标记然后重新提交git add 冲突文件 git commit -m resolve conflict git push关于git pull是直接merge还是rebase我的观点是个人项目随便怎么都行多人协作的共享分支优先用--rebase保持提交历史是一条直线更好看git pull --rebase真正需要特别小心的是git push -f。这个命令会覆盖远程分支的提交历史如果操作在共享分支上可能把别人的提交抹掉。它只适合修复自己刚推上去的错误提交其它时候都要克制。3.3 .gitignore和分支保护两个“一开始就要做”的设置.gitignore文件的作用是告诉Git哪些文件不进版本管理。很多新手会把node_modules、target、.env这类文件推到仓库里既拖慢仓库体积也可能泄露敏感配置。一个比较通用的模板长这样node_modules/ dist/ build/ target/ *.log .env .DS_Store .idea/ .vscode/写好之后提交一次即可。不过要注意.gitignore只能“防住”还没有被跟踪的文件。如果一个文件已经存在于仓库历史里了之后再把它加进.gitignore并不会让它消失需要执行git rm --cached来解除跟踪。分支保护是另一个容易被忽略的设置。在Gitee仓库的“管理→基本设置→分支设置”里可以把默认分支设为保护分支。保护以后成员不能直接向该分支推送代码只能通过Pull Request来合并相当于在流程上强制加入代码评审。小团队一开始会嫌麻烦但用过几次就会发现它对项目质量的兜底非常明显。4. Pull Request与Issue团队协作的正确打开方式4.1 为什么推荐PR而不是直接push到masterPull Request简称PR在中文语境里常被翻译成“拉取请求”听起来有点绕但做的事情很明确你把自己分支的改动提交给项目维护者请求对方审核并合并。可以把它类比成写文章——先写好草稿交给编辑审编辑确定没问题后才正式发布而不是你写完就直接印出来。就算只有两个人协作我也建议走PR流程。原因很实际每一次PR都记录了完整的变更背景事后回看代码历史能知道“这个功能为什么这么改”。合入前有审查环节明显的问题在合入之前就有机会被发现而不是等代码进了主分支再补救。如果配合CIPR通过自动构建之后才允许合并能挡住不少低级问题。很多团队一开始觉得PR是“大公司流程”小团队没必要。结果往往是成员直接在master上提交提交信息乱七八糟出了问题也很难回滚。PR不是仪式感它是让协作留痕最便宜的方式。4.2 一个完整的PR从发起到合并的每一步假设你在feature/login-log分支上提交了代码并推送到Gitee现在想把它合入master。完整流程是回到Gitee仓库首页push成功后页面上会出现“新建Pull Request”按钮。进入新建PR页面左侧选源分支feature/login-log右侧选目标分支master。系统会自动对比两个分支的代码差异先确认差异是否符合预期。填写PR标题和描述描述里写明这个改动解决什么问题、涉及哪些模块。如果有关联的Issue在描述里用#Issue编号提到它PR和Issue会自动关联起来。点击“创建Pull Request”自动进入评审状态。审查人看到PR后可以对具体代码行发表评论也可以整体提修改意见。你可以在评论下方回复形成讨论记录。代码修改通过后回到PR页面点击“合并”选择“合并 Pull Request”。合并之后顺手删除远程的feature/login-log分支。本地分支如果保留太多容易让仓库管理变得混乱建议本地也及时清理git branch -d feature/login-log4.3 Issue管理标签、里程碑一个都别省小团队最容易出现的情况是“需求靠口头传达问题靠聊天记录”。Issue就是用来改变这种状态的一个需求、一个Bug、一个改进想法都可以在Gitee仓库的“Issue”页面里建一条记录。给Issue打标签是低成本高收益的习惯。比如bug、feature、documentation、priority: high具体标签按项目实际情况定义即可。里程碑适合用来规划版本比如v1.0、v1.1把对应的Issue挂到里程碑下一眼就能看出这个版本还剩哪些事没做完。不需要引入重型项目管理工具Git时代的协作需求在Gitee这一套里基本都能覆盖。5. 免费的Gitee Pages个人项目展示的一条捷径5.1 用Pages把一个静态站点部署上去Gitee Pages是一项免费服务适合托管静态网站内容。最常见的用法有两种一是个人博客或项目文档网站二是前端演示页面。不需要自己准备服务器仓库里的HTML、CSS、JS或者通过Hugo、Jekyll、VuePress这类工具构建出来的静态文件都能直接发布成可访问的网址。开启方式很直白仓库页面找到“服务→Gitee Pages”选择要部署的分支比如master目录用根目录点击“启动”。平台会自动拉取分支内容并发布。如果用的是VuePress这类构建工具仓库里保存的应该是构建后的dist目录内容而不是源码目录。需要区分的是Pages服务只适合纯静态站点。如果你的项目需要后端动态渲染、需要操作数据库Pages架不起来得另找应用托管方案。但在个人博客、项目门面页、简历页这些场景下Pages是真的够用又省心。5.2 绑定域名与部署等待这两个高频问题如果你的站点想用一个自己的域名在Gitee Pages页面里填入域名然后到DNS服务商处添加一条CNAME解析指向Gitee提供的Pages地址。解析生效之后访问自己的域名就能打开站点。绑定之前要确认仓库名和域名之间不会引起路径冲突避免资源加载404。另一个被反复问到的问题是改完代码、push之后为什么Pages页面没有变化因为Pages在多数情况下不会像云服务那样推送后秒级更新你需要到Gitee Pages页面手动点击“更新”按钮重新发布或者等平台缓存的自动刷新。刚启动服务或刚更新完浏览器访问出现404或旧页面都很正常过一会儿再强制刷新就好。提示Pages 部署前先在本地生成静态文件并确认路径正确。如果站点部署在子路径下资源引用尽量用相对路径否则上线后样式和脚本会全部加载失败。6. 我踩过的几个Gitee坑和对应的解决办法6.1 仓库体积限制与大文件的处理方式Gitee免费仓库有体积限制个人项目里如果塞了比较大的文件很容易撞线。比如一个项目里附带了几十MB的测试视频、安装包push时收到“文件超出大小限制”的报错是常有的事。解决思路主要有三个从源头排除构建产物、依赖包、本地缓存一律不进版本管理交给.gitignore。用LFS管理大文件先执行git lfs install再对指定类型执行git lfs track *.zip之后正常提交即可。LFS会把大文件内容单独存储Git仓库里保存的只是指针。纯粹的文件分发不要通过Git仓库做用Gitee的Release附件功能上传更合适。需要提醒的是就算加了LFS免费空间额度也是有限的不要以为一劳永逸。视频、镜像这种体积特别夸张的文件最好的去处其实不是任何Git平台。6.2 Windows上文件大小写导致的“莫名其妙”Windows默认的文件系统不区分大小写但Git区分大小写。这会造成一种很诡异的情况你想把Readme.md改名为README.md改完之后git status却提示没有任何变化。原因就是Windows文件系统层面认为这是同一个文件但Git记录的路径大小写已经变了。解决办法是显式用Git命令重命名git mv Readme.md README.md git commit -m Rename Readme to README如果已经出现混乱可以临时设置大小写敏感开关git config core.ignorecase false这个坑不常遇到一旦遇到就会很困惑尤其在团队里有人用Mac有人用Windows时更容易暴露。6.3 push过程中端失败与多账号配置push失败可以说是2021年最常见的Git问题之一。除了网络波动更多时候是地址配错了。用git remote -v查看当前仓库的远程地址确认用的是SSH还是HTTPS。如果你发现push时一直提示输入密码大概率是在用HTTPS地址。想彻底换成SSH执行git remote set-url origin gitgitee.com:用户名/仓库名.git如果一台电脑上要管理多个Gitee账号比如个人号和工作号推荐用SSH配置文件区分。在~/.ssh/config里加一段Host gitee-work HostName gitee.com User git IdentityFile ~/.ssh/id_ed25519_work Host gitee-personal HostName gitee.com User git IdentityFile ~/.ssh/id_ed25519_personal之后克隆仓库时把地址里的gitgitee.com换成gitgitee-work或gitgitee-personalGit会自动选择对应的密钥认证。这个方法我在多账号场景下一直用到现在再也没有混乱过。顺手整理一个排查对照表遇到问题可以直接照着找报错或现象可能原因解决办法Permission denied (publickey)SSH Key未添加或不是当前账号检查公钥是否已配置到Giteefailed to push some refs远端领先本地git pull 后再pushRepository size exceeded仓库超出体积限制排除大文件迁移到LFS每次push都输密码使用HTTPS地址改用SSH地址或配置个人访问令牌文件大小写改动不生效Windows不区分大小写用git mv重命名设置ignorecase false最后再分享一个小技巧提交信息别偷懒。多花十秒钟写一条能说清来龙去脉的commit message比以后花十分钟翻历史猜代码要划算得多。Gitee和Git本身不强制这些但配合PR和Issue之后这套组合能真正把一个项目的历史整理得明明白白。工具始终是工具真正让协作顺畅的还是流程和习惯。
阅读完成 · 觉得有帮助？
