chanlier这几年聊到代码托管，国内开发者的选择清单里，Gitee基本是绕不开的一个名字。作为国产代码托管平台的代表，它从早期被当成GitHub的“备用镜像”，到现在成为很多团队日常开发、协作、部署的主阵地，这个过程本身就很值得聊聊。这篇文章不打算列那些官网就能看到的功能清单，而是想以一个实际使用者的角度，拆一拆Gitee为什么能成为本土开发者的效率新引擎，以及你从注册账号到跑通完整协作流程，到底该怎么做、会遇到哪些坑。
1. Gitee是怎么一步步成为“效率新引擎”的
1.1 本土化不是一句口号，而是实打实的使用差异
很多人在讨论Gitee的时候，总喜欢把它和GitHub放在一起做对比，然后得出一个“功能差不多、生态差很远”的结论。这个结论在五年前基本成立，但放到今天已经不太准确了。Gitee最大的优势从来不是“比GitHub多了什么黑科技”，而是它把“本土开发者日常使用中最容易卡住的那几件事”全部做顺了。
速度就是最直观的一个点。国内访问GitHub，尤其是拉取大仓库、下载Release附件的时候，速度经常让人抓狂，运气不好连网页都打不开。Gitee的服务器就在国内，clone和push的速度基本是秒开，这个体验上的差距，用一次就回不去了。还有一点容易被忽略：Gitee的网页终端和IDE插件对国内网络环境的适配做得更细，比如在推送代码失败时，它给出的错误提示是中文的，而且会直接告诉你“可能是网络问题，建议检查代理配置”，而不是甩一段英文报错让你自己去搜。
再说登录和集成。Gitee支持手机号一键注册、微信扫码登录，这两个能力在国内场景下太重要了。GitHub你还要先注册邮箱、可能还要验证代理，Gitee这边真的就是扫个码的事。这还不算完，Gitee的企业版和Gitee Go（持续集成服务）都支持直接用手机号登录的账号体系，也就是说从注册到进入团队项目，全程不需要跑第二遍身份流程。这些细碎的体验叠加起来，才是“本土化”三个字的真实含义。
1.2 免费策略和GitHub形成的互补关系
另一个让Gitee快速起量的原因，是它的免费策略非常务实。GitHub的免费账户虽然也能建私有仓库，但在团队协作人数、部分高级功能上有不少限制。Gitee的免费个人版直接给了不限数量的私有仓库，这在个人开发者、学生党、小团队里非常受欢迎。我自己身边就有不少朋友，把一些“不想公开但需要多设备同步”的代码直接放到Gitee私有仓库里，当网盘用。
还有一种很常见的使用方式，就是“GitHub存主仓、Gitee做镜像”。很多开源项目为了兼顾国际影响力和国内下载体验，会把GitHub作为主开发仓库，然后通过Gitee的仓库镜像功能自动同步一份到国内。这样一来，国外用户用GitHub访问，国内用户从Gitee拉代码，两边都不卡。对于项目作者来说，这等于多了一个免费的高可用分发节点，而且Gitee的镜像同步配置很轻量，设置一次之后基本不用管。这种互补关系，恰恰说明Gitee不是要“取代”谁，而是解决了GitHub在国内环境下的一些实在痛点。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 从注册到第一个仓库：Gitee实操全流程
2.1 注册、实名认证与账号初始化
如果你想现在就动手试试，第一步自然是注册账号。打开Gitee官网，直接用手机号注册就行，中间会要求你设置用户名和密码。这里有个小建议：用户名尽量和你的GitHub用户名保持一致，后面做双仓镜像或者跨平台同步的时候会省很多事。
注册完成之后，最好顺手把实名认证做了。Gitee的实名认证是通过支付宝或微信的实名信息完成的，整个流程大概一分钟。为什么强调这一步？因为后面你想要开通Gitee Pages、使用Gitee Go、甚至创建Issue时，都可能会遇到需要实名验证才能继续的地方。我有一次帮同事建仓库，他跳过了实名认证，结果在创建Issue时一直报“验证码错误”，排查了半天才发现是实名信息没补全。这种事情提前做完，省得后面卡壳。
账号初始化还有一个容易被忽略的点：绑定邮箱。虽然手机号是主要登录方式，但你在用Git命令行推送代码时，提交记录里需要用到邮箱，Gitee也默认要求你关联一个邮箱才能正常操作。在“设置 -> 基本设置 -> 邮箱管理”里绑定一个常用邮箱，并把“仓库操作通知”打开，这样团队的评审提醒、Issue回复、CI构建结果都会第一时间发到邮箱里。
2.2 创建仓库：关键参数一次说清
在Gitee首页右上角点“新建仓库”，会进入一个参数配置页。这几个参数我一个个说：
仓库名称：建议全小写字母加连字符（比如my-first-repo），不要用中文，也不要混用大写。一个原因是很多工具链对中文路径支持不好，另一个原因是团队里其他人clone时不用去猜大小写。
路径：这是仓库访问地址的后缀，通常会自动跟着仓库名称走。如果仓库名称被占用了，你可以改这里。注意路径一旦创建，改起来比较麻烦，会牵扯到很多链接和配置，所以一开始就定好。
开源许可证：如果选“公开”，建议顺手选一个开源许可证，比如MIT、Apache-2.0或者GPL-3.0。许可证不是随便填的，它决定了别人能不能用、能不能商用、要不要开放源码。这个后面我会专门讲，这里先记住一个原则：个人学习项目选MIT最省事，想防止别人商用就加个GPL，公司内部项目直接选“私有”就行。
初始化仓库：推荐勾选“初始化仓库”，并且加上README文件、.gitignore模板和开源许可证。好处是仓库创建完就有完整结构，你本地执行clone就能直接开始干活，不用再手动建README然后走一遍add、commit、push。
.gitignore模板：Gitee提供了很多现成模板，比如Java、Python、Node.js、微信小程序等。选一个和你项目匹配的，它会自动生成一份忽略文件，把编译产物、依赖目录、本地配置文件排除在版本管理之外。这个小动作能避免很多“代码没改几行，提交记录里全是临时文件”的尴尬场面。
2.3 首次推送代码：HTTP和SSH两条路
仓库建好之后，第一次推送代码我建议先用HTTP方式，因为配置最少，出问题也好排查。新仓库的首页会直接给出完整的命令示例，照着执行就行：
bash复制# 全局配置（如果之前没配过）
git config --global user.name "你的用户名"
git config --global user.email "你的邮箱"
# 在项目目录里初始化仓库并关联远程地址
git init
git remote add origin https://gitee.com/你的用户名/你的仓库名.git
git add .
git commit -m "first commit"
git push -u origin master
执行到最后一步时，会弹出一个窗口要求输入Gitee的用户名和密码。这里输入的是你的Gitee登录密码，不是注册时用的手机验证码。如果开启了双重认证，则需要使用私人令牌（Personal Access Token）代替密码，这个令牌在“设置 -> 安全设置 -> 私人令牌”里生成。
HTTP方式的好处是直观，缺点是每次push都要输密码（除非你配置了凭据存储）。所以第二条路就是SSH方式，这也是我强烈推荐长期使用的方式。先在本地生成SSH密钥：
bash复制ssh-keygen -t ed25519 -C "你的邮箱" -f ~/.ssh/id_ed25519
Windows用户如果没有ssh-keygen命令，多半是没装OpenSSH客户端，在“设置 -> 应用 -> 可选功能”里添加即可。生成完成后，复制公钥内容：
bash复制cat ~/.ssh/id_ed25519.pub
然后到Gitee的“设置 -> 安全设置 -> SSH公钥”里粘贴保存。以后推送代码前，把仓库的远程地址换成SSH格式：
bash复制git remote set-url origin git@gitee.com:你的用户名/你的仓库名.git
换完之后再执行git push，你会发现不再要求输入密码，直接就能推送成功。
2.4 SSH免密配置之后，这些坑才真正开始
SSH免密虽然方便，但配置完之后有几种情况容易让人蒙圈。
第一种是电脑换了或者系统重装了，新机器上没生成密钥，或者生成的密钥没有添加到Gitee，这时候push会报Permission denied (publickey)。解决办法很简单：在新机器上重新执行一遍ssh-keygen，把新公钥添加到Gitee后台。注意旧机器上的私钥文件如果拷过来了，要确保权限没问题，否则SSH会拒绝使用。
第二种是多个Git平台共存。比如你同时用GitHub和Gitee，两边分别生成不同的密钥对，这时你需要在~/.ssh/config文件里为不同域名指定不同的密钥文件：
code复制Host github.com
HostName github.com
User git
IdentityFile ~/.ssh/id_ed25519_github
Host gitee.com
HostName gitee.com
User git
IdentityFile ~/.ssh/id_ed25519_gitee
配置完之后，分别测试一下：
bash复制ssh -T git@github.com
ssh -T git@gitee.com
两边都能返回欢迎信息说明配置成功。这个操作看起来简单，但很多人就是因为没写config文件，导致配置了Gitee的密钥之后，GitHub突然推不了代码，反过来也一样。
第三种是修改过用户名的场景。如果你在Gitee后台改过用户名，原来SSH格式的远程地址会失效，因为SSH路径里带了用户名。这时候用git remote set-url更新一下远程地址就行，别傻乎乎地重新生成密钥。
3. Gitee Pages与项目展示：免费托管网页的完整方案
3.1 “Gitee Pages没有了吗”？真实情况是……
在网上搜索Gitee相关的问题，出现频率最高的一个就是“Gitee Pages没有了吗”。这里我可以很明确地说：Gitee Pages还在，但它的使用门槛和以前不一样了。
最早的时候，Gitee Pages几乎和GitHub Pages一样方便，绑定手机号就能用，一键部署博客、项目文档首页都非常流畅。后来因为合规要求，Gitee Pages改为需要完成实名认证才能开通，而且每次部署需要手动在后台点一下“更新”，不能再通过git push自动触发生成。就是这两个变化，让很多人感觉“Pages是不是凉了”。其实它还在，只是从“无脑用”变成了“需要认真对待的项目资源”。
如果你只是想给个人博客或者项目演示页找个免费的国内托管方案，Gitee Pages依然值得用。尤其你的目标用户主要在国内时，Gitee Pages的访问速度和国内CDN覆盖比GitHub Pages好很多。但如果你希望实现“push代码后自动部署页面”的完整工作流，那Gitee Pages就不太合适了，要么手动更新，要么借助Gitee Go这样的CI服务去实现。
3.2 从零部署一个Pages站点
假设你已经有一个静态网站项目（比如VuePress博客、Hexo博客，或者最简单的HTML页面），想通过Gitee Pages上线。操作步骤并不复杂：
-
把静态文件推送到Gitee仓库里。我建议单独建一个仓库，不要和源码混在一起。比如源码放在
blog-source仓库，最终生成的静态文件放在blog仓库。 -
确保仓库里有一个
index.html文件。Gitee Pages默认会从仓库根目录或你指定的目录读取首页。 -
进入仓库页面，点击“服务 -> Gitee Pages”。如果是第一次使用，会跳转到实名认证页面，完成认证后再回来。
-
在部署页面里，选择要部署的分支（一般选
master或main），指定部署目录（如果静态文件在根目录，填/），然后点击“启动”。 -
等待片刻，页面会生成一个形如
https://你的用户名.gitee.io/仓库名/的访问地址。
部署成功之后，你每次更新内容，需要重新回到这个页面，点击“更新”按钮，才会生成最新的版本。这个“手动更新”的机制是很多人吐槽的点，但换个角度看，它也带来一个好处：每次更新都相当于一次可控的发布操作，不会出现“代码push了、页面却坏了”的情况。
3.3 更新不及时的痛与替代思路
如果你决定把Gitee Pages作为主要站点托管方案，我建议你做好一个辅助策略：保留一份页面源码的本地构建产物。什么意思呢？就是别把构建流程和Pages部署耦合得太紧。
比如我用Hexo写博客，会先把hexo generate生成的public目录推到Gitee仓库，再手动触发Pages更新。这种情况下，即使Gitee Pages某个时间段访问不稳定，或者需要重新实名验证，我本地都还有完整的构建产物，随时可以切换到其他托管平台。
另一个常见的替代思路是：Gitee仓库本身也可以作为“纯静态资源托管”来用。你可以把项目的Release附件、安装包、配置文件直接放到仓库里，访问https://gitee.com/你的用户名/你的仓库名/releases就能下载，不需要额外开Pages。对于很多小工具项目来说，这个方式简单直接，比维护一个完整站点更实用。
4. 团队协作场景下的Gitee高效玩法
4.1 用PR和Issue跑通规范的协作流程
单个开发者用Gitee，核心诉求就是代码托管和版本管理；但一旦进入团队协作，Gitee的价值会进一步放大。我最推荐团队优先用起来的两个功能是Pull Request（简称PR）和Issue。
PR是Gitee上最核心的协作机制。它的流程是：开发者从主仓库fork一份到自己账号下，或者直接在仓库里创建一个功能分支，在本地上完成代码修改，然后push到远端，最后提交一个PR请求把改动合并回主分支。这个流程最大的好处是：所有代码变更都会经过一次显式的审查过程，而不是直接往主干上推。
用Gitee的PR功能时，我建议提交PR的描述信息写得足够详细。至少包含三部分：这个PR做了什么、为什么这么做、怎么测试验证。Gitee支持在PR里直接@指定的人，也支持关联对应的Issue，比如在描述里写Closes #12，合并PR时就会自动关闭编号为12的Issue。这个联动机制，能让团队的开发任务、代码变更和文档记录串成一条完整的链路。
4.2 分支命名规范：别让主干变成事故现场
关于Gitee的分支命名，很多团队一开始不重视，结果代码量大了之后，主干分支上一堆零散的提交记录，出了线上问题都找不到对应代码是谁改的。这里我给出一套经过验证的命名方案：
master或main：主干分支，永远保持可发布状态。develop：开发集成分支，功能分支开发完先合并到这里。feature/xxx：功能开发分支。比如feature/user-login表示开发用户登录功能。bugfix/xxx：修复Bug的分支。release/v1.0.0：发布分支，只做发布前的回归和修修补补。hotfix/xxx：线上紧急修复分支，直接基于master创建，修完合并回master和develop。
这套命名规则的核心思想是“通过分支名表达意图”。任何人看到feature/payment-wechat就知道这是微信支付功能的开发分支，看到bugfix/order-discount就知道这是在修订单折扣的问题。Gitee后台也支持为分支设置保护规则，比如master分支不允许直接push，必须通过PR合并，这在“管理 -> 分支保护”里可以配置。开启之后，主干分支的安全性和可追溯性会大幅提升。
4.3 开源许可证怎么选：一次讲透
“Gitee开源许可证选什么”是一个被搜烂了的问题。我直接给你一张速查表：
| 许可证 | 是否可商用 | 是否必须开源 | 是否必须保留版权声明 | 适用场景 |
|---|---|---|---|---|
| MIT | 允许 | 否 | 是 | 个人项目、工具库，希望被广泛使用 |
| Apache-2.0 | 允许 | 否 | 是 | 企业级项目，需要明确专利授权 |
| GPL-3.0 | 允许 | 是（衍生作品也要开源） | 是 | 想防止别人闭源商用的项目 |
| BSD-3-Clause | 允许 | 否 | 是 | 和MIT类似，附带禁止用作者名义推广的条款 |
初学者最容易犯的错误是：写了一个工具类项目，随手选了个GPL-3.0，结果别人想集成到商业项目里发现走不通，反而影响了项目的传播。如果你希望项目被更多人使用，MIT或者Apache-2.0会更合适。反过来，如果你明确不想让自己的代码被闭源商用，GPL-3.0才派上用场。
4.4 微信开发者工具和Gitee的联动
这个场景在热词里出现频率很高，值得单独说一下。很多人做微信小程序项目，团队协作时会选择Gitee作为代码托管平台。微信开发者工具本身内置了Git面板，你可以直接把Gitee仓库clone到本地，然后用开发者工具打开项目目录。
具体操作是这样：先在Gitee上建好仓库（建议初始化README和.gitignore），然后在本地执行：
bash复制git clone https://gitee.com/你的用户名/小程序项目.git
克隆完成后，打开微信开发者工具，选择“导入项目”，目录指向刚才克隆下来的文件夹，填写自己的AppID，工具会自动识别项目结构。之后你在工具里的每次保存，都可以通过Git面板完成提交和推送。
这里有两个细节容易踩坑。第一，project.config.json文件里如果包含了你个人的AppID，建议把它加入.gitignore，或者用Git的skip-worktree功能忽略它的改动，否则每次提交都可能把别人的AppID覆盖掉。第二，多人协作时，开发者工具生成的miniprogram_npm目录属于编译产物，不要提交到Gitee仓库，让每个开发者在本地单独执行构建，否则仓库会变得异常臃肿。
5. 高频问题排查与避坑实录
5.1 git did not exit cleanly：90%的人卡在配置上
在Windows上使用TortoiseGit或者某些IDE的Git插件时，很容易遇到git did not exit cleanly (exit code 1)这类报错。这个报错本身只是一个“壳”，真正的错误原因一般藏在更早的控制台输出里。
最常见的三种原因：
第一，user.name和user.email没有配置。Git在提交时必须有这两个信息，如果缺失就会报错。解决办法：
bash复制git config --global user.name "你的名字"
git config --global user.email "你的邮箱"
第二，换行符转换问题。Windows的CRLF和Linux的LF不一致，导致文件状态一直显示已修改。建议统一配置：
bash复制git config --global core.autocrlf true
第三，本地分支和远程分支没有关联。首次push时忘记加-u参数，后续push就会提示找不到上游分支。用git push -u origin 分支名重新关联一次即可。
5.2 创建Issue一直验证码错误
这个问题的根源，我在前面提到过：多数情况是账号没有完成实名认证，或者没有绑定手机号。Gitee的Issue创建流程里会触发一个人机验证，如果账号信息不完整，这个验证就会一直失败。另外还有一个容易被忽略的点：清理一下浏览器缓存和Cookie，因为Gitee的验证码服务偶尔会和过期Cookie冲突。
如果以上都试过还是不行，换一个浏览器试试。我实测过Chrome和Edge都没问题，但某些IE兼容模式或者极速模式切换不当的浏览器，会卡在这个验证上动弹不得。
5.3 推送免密失效的几种情况
前面说过SSH免密配置后，偶尔会遇到失效的情况。这里补充一个更隐蔽的原因：如果你同时使用了Gitee的邮箱和手机号账号体系，在网页上切换了登录账号，可能会导致本地缓存的凭据失效。
还有一个情况是针对HTTP方式的：虽然你在Windows凭据管理器里保存了密码，但Gitee推出了私人令牌机制之后，如果你开启了双重认证，旧的密码凭据就无法再用于Git操作。这时候你需要生成一个新的私人令牌，然后在远程地址里带上：
bash复制git remote set-url origin https://用户名:私人令牌@gitee.com/用户名/仓库名.git
当然，直接配置SSH密钥还是最省心的一劳永逸方案。
5.4 几个消耗时间的日常坑
还有一些日常使用中很容易消耗时间的小问题，我放在一起说。
Gitee仓库首页不显示图片：很多人在README里放了本地图片的相对路径，结果仓库页面打开是裂图。解决办法是图片要么上传到仓库里用相对路径引用，要么用raw链接，要么放到Gitee自带的图床里。最常见的是直接在README里引用https://gitee.com/用户名/仓库名/raw/master/images/xxx.png这种格式。
clone大仓库超时：如果仓库里有大量历史提交和二进制文件，clone时容易超时。建议加--depth 1参数做浅克隆，只拉取最新版本：
bash复制git clone --depth 1 https://gitee.com/用户名/仓库名.git
仓库容量超限：Gitee免费仓库有1GB的大小限制。如果仓库接近上限，先检查有没有大文件被误提交，然后可以用git filter-branch或者最新的git filter-repo工具重写历史。这个操作有一定风险，操作前务必做好备份。
个人开发者使用：如果你只是个人开发者，我建议把Gitee当成一个“云端代码保险箱”，所有重要项目都推一份上去，尤其是那些写了一半的练手项目。本地磁盘损坏不可怕，可怕的是Git仓库的完整历史也一起没了。Gitee的私有仓库免费名额已经足够用了，把这个习惯养成，长期来看非常值。
我在实际使用中还有一个体会：Gitee的代码托管能力本身已经足够稳定，真正让团队效率提升的，反而是它周边那些“看起来不起眼”的功能。比如仓库看板、里程碑管理、自动构建、部署集成，把这些功能串起来使用，Gitee就不只是一个存放代码的地方，而更像一个轻量级的研发管理平台。对很多没有专职运维、也不想维护一套重型项目管理系统的团队来说，这种“轻量但闭环”的体验非常实用。建议你在跑通基本流程之后，再花半个月时间把Gitee Go和仓库看板用起来，那才是它真正发挥“效率引擎”作用的时候。