Gitee实战指南：从SSH密钥配置到Pages部署与开源许可证选择

1. Gitee为什么能成为开发者生态的底层设施

先说个实际现象。这几年不管是做外包、创业公司做项目，还是传统企业搞内部系统，很多团队第一步不是开会定方案，而是先建仓库。仓库建在哪？国内团队用Gitee的比例越来越高。我的经验是，Gitee已经不止是"GitHub的国内替代品"那么简单了，它在我接触的项目里，扮演的是整个研发流程的起点和连接器，从代码托管、分支管理、Code Review，到文档、发布静态站点、甚至开源项目运营，都能在一个平台上闭环，这些恰恰是开发者生态最底层的需求。

为什么用户会从GitHub迁移或同步过来？核心原因其实很朴素：访问速度。我在国内直接操作GitHub时，clone一个稍大的仓库经常会卡在几百KB每秒，而Gitee上同样的公开仓库基本是满速。再加上平台本身做了很多贴近国内开发习惯的设计，比如私有仓库免费、内置CI/CD、Pages服务、企业级权限管理，这些功能叠加起来，就让"把代码放Gitee"变成了一件不用犹豫的事。

再往深一层看，Gitee和数字化转型的关系，我认为不在"上云"这种宏大叙事里，而在最实际的流程线上化里。传统企业做研发管理，早期用SVN、用文件服务器、甚至用QQ传代码，这种方式的问题是权限粗放、历史不可追溯、多人协作靠吼。但把代码和需求搬到Gitee之后，整个研发过程就有了"数字痕迹"：谁提交了什么、哪个分支合了哪次PR、某个版本对应哪个Tag，全都能检索。这个看起来不起眼的改变，其实是很多企业数字化改造里落地最快、见效最明显的一步。

当然，Gitee和GitHub、GitLab这些平台都不是零和关系。很多开源项目会做双仓同步，GitHub做国际展示，Gitee做国内加速和镜像下载。这种布局下，Gitee实际上成了国外开源技术和国内开发者之间的一个"加速枢纽"。所以我在后续文章里会重点讲实操：密钥配置、代码上传下载、Pages部署、许可证选择、常见故障排查。这些内容都是我在真实项目里一遍一遍踩坑踩出来的，希望能帮你省掉那些不必要的折腾。

2. 开工前的环境准备：Git与SSH密钥配置

2.1 本机Git环境检查与安装

不管你是刚接触版本控制的新人，还是用了几年Git的老手，我都建议在配置Gitee之前先花一分钟确认本机环境。这一步看着简单，实际坑很多。我见过不止一个同事，在配置密钥时报错，查到最后竟然是本机有两个Git版本，环境变量指向了旧版。

在Windows上，打开命令行执行：

git --version

如果输出类似git version 2.40.0，说明已安装。如果没有，去官网下载安装包，一直下一步即可。安装时有个容易被忽略的选项：Git Bash的安装方式，建议保留默认，后续操作命令在这个终端里最顺手。

在macOS上，执行同样的命令，如果没有会弹出安装提示，也可以用Homebrew安装：

brew install git

Linux发行版则根据包管理器安装，比如Debian系的：

sudo apt update && sudo apt install git

装完之后，第一件事是设置全局用户信息，否则提交记录里没有作者信息，代码传上去也无法对应到具体人：

git config --global user.name "你的名字" git config --global user.email "你的邮箱"

这里有个细节：邮箱建议和Gitee注册邮箱保持一致，这样你在Gitee上的提交记录能正确关联到账号，贡献图和提交历史才不会"张冠李戴"。

2.2 生成SSH密钥并添加至Gitee

配置SSH密钥是Gitee使用中最高频、也最容易出问题的环节。先说为什么要配：每次push和pull都输入账号密码其实也能用，但一是麻烦，二是某些自动化场景（比如CI/CD服务器拉代码）没法输密码。SSH密钥相当于一把本机持有的"钥匙"，Gitee持有对应的"锁"，配对成功后就免密操作了。

生成密钥的命令：

ssh-keygen -t ed25519 -C "你的邮箱@example.com"

这里我推荐ed25519算法而不是传统的RSA，原因是密钥更短、安全性更高、生成速度也快。如果你的Git版本比较老，不支持ed25519，再退回RSA：

ssh-keygen -t rsa -b 4096 -C "你的邮箱@example.com"

执行后会出现提示：

Generating public/private ed25519 key pair. Enter file in which to save the key (/c/Users/你的用户名/.ssh/id_ed25519):

直接按回车用默认路径。接着会要求设置passphrase，这个可以留空，但如果你在共享电脑上工作，建议设置一个，代价是每次使用要输一遍密码。设置完成后，终端会输出一个随机图案和密钥指纹，到这里密钥就生成好了。

然后查看公钥内容：

cat ~/.ssh/id_ed25519.pub

复制输出的整段内容，登录Gitee，进入设置 -> SSH公钥，把内容粘贴进去，标题可以写"我的电脑"或"办公机器"，方便以后区分。添加完成后，测试连通性：

ssh -T [e-mail]

如果配置成功，会返回类似Hi 用户名! You've successfully authenticated, but Gitee does not provide shell access.的提示。如果你第一次执行这个命令时看到Are you sure you want to continue connecting，输入yes即可。

2.3 配置过程中的常见错误：多密钥冲突

搞定了上面这些，其实你已经能用了。但到了多台电脑或者一个电脑多个代码平台（GitHub+Gitee同时用）的场景，就会遇到我踩过的坑。默认情况下，SSH会把~/.ssh/id_ed25519作为唯一密钥去连接所有服务器，这就导致GitHub用的密钥和Gitee用的密钥冲突，总是连不上其中一个。

解决办法是配置~/.ssh/config文件。假设你希望Gitee走专用密钥：

Host gitee.com HostName gitee.com User git PreferredAuthentications publickey IdentityFile ~/.ssh/id_ed25519_gitee

然后生成密钥时指定文件名：

ssh-keygen -t ed25519 -C "[e-mail]" -f ~/.ssh/id_ed25519_gitee

再把对应的公钥添加进Gitee。这样连接时，系统会根据域名自动挑选正确的密钥。很多人在这一步卡住，我建议先按这个思路排查，比反复重新生成密钥有效得多。

3. 代码仓库实操：上传、下载与日常协作

3.1 从零上传代码到新建仓库

把本地代码推到Gitee，是我被问最多的问题。很多初学者卡在第一步：本地有一个项目文件夹，Gitee上建了一个空白仓库，两边怎么打通？

先在Gitee网页端新建仓库，填仓库名、勾选是否初始化README、选择许可证。要注意：如果你准备从本地已有代码推上来，就不要勾选"初始化仓库"，也就是不要生成README、.gitignore。否则本地仓库和远程仓库的提交历史不相关，推送时会报rejected，还得先合并，麻烦得很。

仓库建好后，页面会给出两套指令。一套是"已有仓库"的推送方式。在本地项目目录执行：

git init git add . git commit -m "初始化提交" git remote add origin [e-mail]:你的用户名/仓库名.git git push -u origin master

这里有个关键点：Gitee新仓库的默认分支名可能是master，也可能因平台调整变成main。你在远程仓库页面能看到默认分支名。如果本地推送的是master，远程默认是main，会提示创建了一个新的分支而不是往默认分支推送，团队协作时容易混乱。我习惯的做法是推送前先确认分支名，不一致就用：

git branch -M main

把本地分支改名后再推送。这一点特别容易忽略，但直接影响后续PR和协作流程。

如果仓库不是从零开始，而是已经有一个remote，想换到Gitee：

git remote set-url origin [e-mail]:你的用户名/仓库名.git

改完直接push就行。

3.2 从Gitee下载代码到本地

下载代码有两种协议：HTTPS和SSH。如果你只是临时下载一份看看，用HTTPS最简单，没有密钥也能clone：

git clone https://gitee.com/用户名/仓库名.git

但如果你要往仓库提交代码，就要用SSH地址。这里有个细节，你在Gitee仓库页面看到的地址默认可能是HTTPS，点一下"克隆"按钮旁边的切换，才能看到SSH格式。clone速度方面，SSH和HTTPS在国内都很快，差别不大，关键是SSH免密，HTTPS每次push要输账号密码。

还有一个使用频率很高的技巧：只拉取指定分支。有些仓库分支很多，默认clone会把所有分支和完整历史都拉下来，既慢又占磁盘。用这个命令：

git clone -b dev --single-branch [e-mail]:用户名/仓库名.git

-b指定分支，--single-branch只拉该分支历史。很多生产环境部署脚本里都用这种方式，避免拉取大量无用数据。

另外，下载特定版本的代码不需要clone整个仓库。Git提供了稀疏检出（sparse checkout），适合仓库很大但只需要某个子目录的场景：

git clone --filter=blob:none --sparse [e-mail]:用户名/仓库名.git cd 仓库名 git sparse-checkout set 子目录名称

这个用法在新版本Git里很成熟，处理Gitee上那些塞了大型二进制资源的仓库时，能省很多时间。

3.3 分支管理、PR与日常协作细节

代码能上传下载之后，协作才是重头戏。Gitee的分支保护和Pull Request流程，在团队内部用得好的话，能极大减少"代码冲突靠微信喊"的尴尬局面。

我在团队里推行的一个工作流是这样的：

1. main（或master）分支设为受保护分支，开启"强制评审"和"强制关联任务"。
2. 每个人的改动都从main切出新分支：

git checkout -b feature/登录模块

3. 开发完推送到远程同名分支，然后在Gitee网页端发起PR。

4. PR里写清楚改动内容和测试结论，审核人通过后合并。

这个流程里Gitee有几个好用的小功能容易被忽略。一个是PR页面的代码对比视图，支持按行评论，Review时可以精准指出问题；另一个是"可合并检查"，代码和最新main有冲突时，页面会明确提示，并且可以网页端自动解决简单冲突。这些能力让远程协作不再依赖"你拉一下我的分支看看"，流程整体透明多了。

分支策略上，个人项目和团队项目建议分开。个人项目可以单分支直推，省事；团队项目至少要有dev和main两层，dev承载日常集成，main只放可发布版本。配合Gitee的标签功能，每个版本一个Tag，回滚时直接定位Tag，别提多方便。

4. 发布网站：Gitee Pages的使用与限制

4.1 Gitee Pages能做什么

代码仓库不只是存档代码，很多开发者把Gitee仓库当成个人网站的托管环境。Gitee Pages可以在仓库基础上直接生成静态网站，支持Jekyll、Hexo、VuePress等常见的静态站点生成器，也可以直接放纯HTML文件。我自己就有个技术笔记博客，用它托管，零成本，还天然和代码仓库绑定，改代码就是改网站。

Pages服务对这几类人特别有价值：个人博客作者、开源项目的文档站点、前端项目的演示预览。尤其是开源项目，README写得再详细也不如一个在线Demo直观，Pages正好补上这个空缺。

具体来说，Gitee Pages支持两种发布方式：一种是普通发布，直接使用仓库根目录或docs目录下的静态文件；一种是Jekyll构建，仓库里放Jekyll源码，平台自动构建生成站点。

4.2 部署静态站的实操步骤

以Hexo博客为例，整个过程不复杂。先在仓库里准备好编译后的文件，Hexo生成的文件在public目录，需要把这个目录内容放到仓库根目录，或者用Git subtree方式推送。最简单的方式是：把public目录内容复制到仓库根目录，推送到Gitee。

然后在Gitee仓库页面找到服务 -> Gitee Pages，选择部署分支，目录选"根目录"，点击启动。正常情况下，几秒钟后页面上会出现一个访问地址：https://用户名.gitee.io/仓库名/，这就是你站点的线上地址。

要注意的是，Gitee Pages启动后会有一个审核过程，内容合规性需要没问题才能通过。我的经验是，个人技术博客、文档站这类内容基本都能顺利通过。如果部署后出现样式错乱，优先看看站点的base路径配置，特别是Hexo的_config.yml里root设置必须包含仓库名。

举个例子，如果你的站点地址是https://用户名.gitee.io/myblog/，那么root要写成/myblog/，否则CSS、JS资源都会从域名根路径去找，全部404。

4.3 常见限制与替代方案

Gitee Pages虽然方便，但有几个限制你要清楚。首先是仅支持静态内容，不含服务端动态环节，像用户登录、留言数据库这些功能是实现不了的，必须借助第三方服务比如LeanCloud或自建后端API。其次是带宽和空间对个人项目够用，但如果你打算存放大量高清图片或视频，就很不合适，建议把大文件放到对象存储，网页里引用外链。

还有一个容易被忽略的点：Pages服务支持自定义域名，但需要绑定备案过的域名。如果你手头的域名没备案，或者不打算折腾备案，直接用默认的gitee.io二级域名就好，省心。

如果你的需求超过了Pages的能力上限，比如要跑Node服务、要WebSocket、要数据库，那就得上云服务器部署。这时候Gitee仓库依然有用，配合Webhook，push代码后自动触发服务器上的拉取脚本，完成部署，形成一套轻量级CI/CD。这个方案我在多个小项目中实践过，成本低，效果也好。

5. 开源许可证怎么选：一次讲清

5.1 为什么要在平台选许可证

Gitee上新建仓库时，会有一个"选择许可证"的选项，很多人直接跳过。等到项目被别的人看到、想用你的代码时，问题就来了：代码到底能不能商用？能不能修改？会不会承担法律风险？没有许可证的开源项目，在法律意义上其实保留所有权利，别人即使看到了代码，也不能合法使用。

所以我的建议是：新建仓库时顺手就选好。这不是形式主义，而是给你的作品一个明确的使用合同。特别是做开源项目的朋友，许可证就是项目的"使用说明书"，直接影响社区能不能放心用你的代码。

5.2 常见许可证对比

Gitee平台上的许可证选项很多，我筛出最常用的几个做对比：

许可证	商用	修改后闭源	修改后必须开源	适用场景
MIT	允许	允许	否	最宽松，适合工具类、库类和个人小项目
Apache 2.0	允许	允许	否	需明确专利授权，适合企业级开源组件
GPL 3.0	允许	禁止	是	强调保护开源生态，适合想要强制开源的场景
AGPL 3.0	允许	禁止	是	网络服务也需开源，适合SaaS类项目
MPL 2.0	允许	允许	修改的文件需开源	折中选择，适合文件级开源

这个表格里的"修改后必须开源"，指的是你基于别人的代码做了修改并对外分发时，修改部分的源码要一并提供，而不是整个衍生项目都要开源。比如你用GPL代码做内部工具、不对外分发，也无需开源。

5.3 个人项目选型建议

对于大部分个人开发者，我的建议是：拿不准就选MIT。它的条款最简单、最不设限，别人用起来没有心理负担，你的代码传播和使用范围会更广。如果你希望代码在修改后也必须开源，就选GPL 3.0。如果你是做基础组件、希望大公司能放心集成进去的，选Apache 2.0，它带了专利授权保护条款，对商业环境更友好。

还有一个小提醒：许可证一旦选定并推广了项目，后续想换会非常麻烦，因为你已经收到的所有贡献都基于旧许可证，要换需要所有贡献者同意。所以最开始要认真选，宁可在项目早期README里写一句"代码暂时以MIT发布，预留换证权利"，也不要后期被迫换证。

6. 常见问题与排查技巧实录

6.1 认证失败、无法clone和push

这一类问题在Gitee使用中占比最高。先列几个高频报错和对应的解决思路。

Permission denied (publickey)：这基本就是SSH密钥没配对成功。按顺序检查：公钥有没有加到Gitee设置里；本机用的是不是正确的密钥文件（多密钥时最容易错）；测试命令ssh -T [e-mail]的返回信息。如果提示的是另一个GitHub用户名，说明SSH走了GitHub的密钥，回到前文说的config文件方法解决。

remote: HTTP Basic: Access denied：这是使用了HTTPS方式但账号密码错误。记住一个容易混淆的点：HTTPS clone时用的密码不是你的登录密码，而是在Gitee设置里生成的私人令牌。在设置 -> 私人令牌里创建，权限按需勾选，然后clone时用它作为密码。

RPC failed; HTTP 413 curl 22：这个报错大多和仓库体积太大有关，尤其是第一次推送历史很长的老项目时常见。解决办法有两个方向：一是检查仓库里是不是不小心提交了大文件，用git filter-branch或者git filter-repo清理历史；二是配置HTTP缓冲区：

git config --global http.postBuffer 524288000

把缓冲区调到500MB，能解决一部分问题。但根治方案还是控制仓库体积。我个人的底线是：仓库大小控制在1GB以内，超过这个量就考虑用Git LFS或者拆仓库。

6.2 仓库大小限制、大文件处理

Gitee对单个文件和仓库总大小都有建议限制。普通仓库里塞进去几百MB的视频、设计稿、数据集，会拖慢clone和push速度，协作体验很差。

处理大文件的正规方式是用Git LFS（Large File Storage）。Gitee也支持LFS，使用方法是：

git lfs install git lfs track "*.psd" git add .gitattributes

git lfs track指定哪些类型文件走LFS存储。之后这些文件的实际内容存在LFS服务器上，Git仓库里只是一个指针引用。其他人在clone时，Git会自动拉取LFS内容，前提是他也装了这个插件。

如果你只是想往仓库放一个超过限制的单个文件，又不想用LFS，也许需要重新审视文件本身：设计稿可以压缩，视频可以转码，数据集可以放网盘然后在README里贴链接。这在工程上是合理取舍，代码库保留的是代码和文档，二进制资产走专业的资产管理方案。

6.3 用Gitee做依赖源：镜像安装工具与自动化基础

Gitee在国内开发者生态里有一个很有分量的角色：开源软件的分发和镜像节点。很多开发者发现，某些工具或依赖包在国外源拉取速度不稳定，而Gitee上常常有热心开发者同步的镜像仓库，可以把这些仓库配置为下载源。

我举一个实际例子。Claude Code这类以CLI方式运行的AI辅助编程工具，安装时会拉取一系列依赖。在我的实操中，通过配置镜像仓库地址，能够明显提高安装速度和稳定性。具体做法是：在Gitee上搜索对应的镜像仓库，拿到HTTPS地址，然后在相关配置文件中指定该地址为源。

需要注意，使用第三方镜像仓库前，先核对仓库的更新时间和描述页，确认是否有活跃维护、是否同步了上游发布版本，避免装到过期或改动过的代码。安全底线是：尽量选择仓库owner明确、star数量高、最近还有提交的项目；如果要用于生产环境，最好自己维护一份镜像并在本地验证校验值。

这个场景背后的逻辑，恰恰验证了Gitee不只是"代码存放处"。当一个平台能承接依赖分发、软件镜像、文档网站、协作流程，它就在事实上成了开发者生态的基础设施。数字化转型落到研发侧，最直观的表现就是这些环节的线上化和标准化。

7. 最后的实操经验总结

前面几章把Gitee的常见面都过了一遍，这里再分享几个我在实际项目中总结的、不太会写进官方文档的经验。

第一，安全和效率要提前设计，不要等出事再补。我在一个团队接手过一个历史仓库，所有人的SSH密钥都绑在个人账号下，员工离职后代码访问权限没有及时回收，差点出了安全事故。后来我强制要求项目仓库使用"受保护分支"，对main开启评审，并定期检查协作成员列表。这比任何监控工具都管用。

第二，README和文档的价值被严重低估。仓库建好，很多人习惯性直接开写代码，README留空。但换一个角度想，Gitee上的仓库就是你和陌生开发者之间的第一张名片。一个拥有清晰项目介绍、许可证、快速开始命令、Screenshots的仓库，获得的star、PR和反馈，要远多于干巴巴只有代码的仓库。这不是运营技巧，而是工程习惯。

第三，多平台同步的工作流值得搭建。很多项目需要在GitHub和Gitee同时维护，手动两边push容易漏。Git本身支持多个remote，你可以在项目里执行：

git remote add gitee [e-mail]:用户名/仓库名.git git remote add github [e-mail]:用户名/仓库名.git

然后推送时一次性推到两边：

git push gitee main && git push github main

也可以配置好之后用git push --all一次性广播。用Gitee的Webhook，还能在push后自动触发其他平台或服务器的同步脚本。这套流程跑通之后，项目维护量基本是"一次写入，多端同步"，非常省心。

最后说一句，工具始终是辅助，真正的生产力来自清晰的流程和稳定的习惯。Gitee的功能面已经覆盖了一个项目从萌芽到发布的大部分场景，把你的日常工作流往这个平台上沉淀一遍，你会发现协作中的很多摩擦其实都是可以规避的。这篇内容里的方法，都是我在真实项目里验证过的，希望能对你的实际工作有直接的帮助。