Gitee从入门到实战：仓库管理、SSH免密、Pages部署与许可证选型指南-代码聚汇网

Gitee从入门到实战：仓库管理、SSH免密、Pages部署与许可证选型指南

Gitee代码托管Git

|难度：普通|阅读约 36 分钟

Gitee这个平台，我前前后后用了快七年。七年前它给我的印象就是“国内能正常访问的Git托管”，如今再回头看，它已经成了很多企业研发流程里离不开的底座。数字化转型这个词听起来很大，落到一线开发者和团队负责人手里，其实就是代码放哪里、协作怎么跑、发布怎么管这些具体到不能再具体的事。这篇就从实际使用的角度，把Gitee从建仓库、传代码、配免密、部署Pages到开源许可证选择这一套流程完整拆开讲一遍，顺便把大家高频遇到的坑也一并解决掉。

1. 为什么说Gitee是数字化转型的“底层引擎”

1.1 从一次业务断档说起

早些年我在一家做产业互联网的公司带开发团队，那时候代码托管用的是海外平台，业务走到高峰期，跨境网络时不时抽风，git clone 和 git push 经常卡在半路，CI流水线一天挂好几次。最要命的是产品团队急着发版，开发那边根本推不动代码，整个发布链路就卡在“代码都传不上去”这个最原始的环节上。

数字化转型本质上是业务的软件化，而软件研发需要一个可靠、稳定、合规的代码资产中心。代码是数字化业务的核心资产，如果这块资产的存储和流转都不可控，上层所有的自动化、DevOps、持续交付就成了空中楼阁。Gitee当时对我们最大的价值，不是功能比海外平台强多少，而是它解决了“代码到底能不能稳定放住”这个最底层的信任问题。

1.2 不只是“中国的GitHub”

很多技术人喜欢把Gitee概括成“中国的GitHub”，这个说法对，但不完整。GitHub是代码托管平台，Gitee早期确实对标它，但这些年它已经横向延伸到了需求管理、缺陷跟踪、CI/CD流水线、代码评审、文档Wiki、团队权限这些研发全链路的能力。

以我们当时的团队为例，整个研发链路是这样的：

产品经理在Gitee上建需求Issue，写明业务背景和验收标准；
开发认领Issue后创建分支，按照 #issue号+描述的规则命名，直接关联需求和代码；
提交代码后通过Pull Request走评审，评审通过后合并；
合并动作触发Gitee Go流水线，自动完成构建、测试、推送镜像；
运维再从制品库拉取产物发布到对应环境。

你会发现，在这个链条里，Gitee已经不是“存代码的仓库”那么简单了，它更像研发流程的操作系统——记录需求来源、代码变更、评审记录、构建结果，整个数字化业务从这里长出来，因此说它是底层引擎并不夸张。

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

2. 从零开始：创建仓库与首次推送代码

2.1 创建仓库时的几个关键选项

不管是企业项目还是个人学习，Gitee的第一步都是“创建仓库”。这个入口在首页左上角的“+”号里，点开后有几个选项需要认真选。

仓库名称是整个项目的身份证。建议格式为 group-project 或 project-module，全小写，用连字符分隔。Gitee上同名仓库在同一个账号或组织下不能重复，所以命名前先在搜索框里查一下有没有同名。

私有/公开的选择要结合项目性质。企业项目默认私有，个人学习项目推荐公开——公开项目可以刷贡献度和个人影响力，别人也能通过你的项目了解你的技术水平，面试时这比简历上写“精通XX”有说服力得多。

初始化仓库这一栏有三个选项：README、.gitignore、开源许可证。很多人第一次创建时嫌麻烦，全部留空，结果后患无穷。README是项目的门面，建议哪怕只写两行也要勾选。.gitignore的作用是过滤掉编译产物、本地配置这类不需要提交的文件，不同语言模板不同，Gitee会按主语言自动匹配。开源许可证先不急着选，后面单独讲。

2.2 新项目首次推送到Gitee（命令行方式）

创建好空仓库后，本地推送的步骤基本是固定的。假设你本地有个写好的项目，终端操作如下：

bash复制# 进入项目目录
cd my-project

# 初始化本地Git仓库
git init

# 添加远程仓库地址，USERNAME换成你的用户名，REPO换成仓库名
git remote add origin https://gitee.com/USERNAME/REPO.git

# 把当前目录所有文件加入暂存区
git add .

# 首次提交，-m后面写提交说明
git commit -m "initial commit: 项目初始化"

# 推送到远程并关联上游分支
git push -u origin master

这里的 -u 参数是 --set-upstream 的简写，意思是把本地 master 分支和远程 master 分支建立关联。下次再提交时，直接 git push 就行，不用重复指定远程和分支名。这一步很多人容易漏，漏了之后每次推送都得打全命令，很烦。

如果远程仓库在创建时已经勾选了“初始化仓库”并生成了README，本地推送前需要先拉取远程内容做一次合并：

bash复制git pull origin master --allow-unrelated-histories

这个操作我会在后面的问题排查里单独解释——它是新手首次推送时最常遇到的障碍之一。

2.3 用VSCode推送代码：图形化操作更省心

不爱敲命令的朋友完全可以用VSCode。先在VSCode左侧扩展面板搜“Git”相关的内置能力，其实不需要装额外插件，VSCode自带Git支持。操作路径如下：

打开项目文件夹，点击左侧“源代码管理”图标（那个分叉树的图标）；
点击“初始化仓库”按钮，本地Git仓库就建好了；
在“更改”列表里点击文件后方的“+”号，把需要提交的文件放到“暂存区”；
在输入框里写提交说明，点击“提交”按钮；
点击底部状态栏的“发布分支”或“同步更改”，第一次会弹窗让你输入远程仓库地址，粘贴 https://gitee.com/USERNAME/REPO.git 即可。

VSCode在首次推送时会自动执行 git remote add 和 git push -u，比终端敲命令直观一些，适合刚入门的朋友。不过我还是建议把命令行学一遍，毕竟线上问题排查时，服务器的终端环境才是最常用的。

3. 推送免密配置：SSH Key全流程

3.1 为什么要做免密

每次推送代码都要输入Gitee的账号和密码，短时间还好，一天推送几十次就比较折磨人。更重要的是，CI/CD流水线在服务器上执行拉取和推送操作时，不可能有人坐在那里输密码，所以免密是自动化流程的前提。

Gitee支持HTTPS和SSH两种远程地址协议：

协议	地址格式	推送时认证方式	适用场景
HTTPS	`https://gitee.com/USERNAME/REPO.git`	用户名+密码/私人令牌	临时使用、部分企业内网环境
SSH	`git@gitee.com:USERNAME/REPO.git`	SSH密钥对	日常开发、CI流水线、长期使用

我个人的建议是：所有长期使用的机器都配SSH Key，一次性配好，之后所有仓库都免密。

3.2 SSH Key生成与配置全过程

SSH Key的生成和配置流程，我整理成下面的步骤：

第一步，生成密钥对：

bash复制ssh-keygen -t rsa -b 4096 -C "你的邮箱"

执行后终端会提示选择保存路径，默认是 ~/.ssh/id_rsa，直接回车就行。接着提示输入密码短语，这里可以直接留空，除非你的安全等级要求极高。生成后会得到两个文件：id_rsa（私钥，绝对不能泄露）和 id_rsa.pub（公钥，需要放到Gitee上）。

注意：密钥的类型和位数，-t rsa -b 4096 是经典稳妥的组合，兼容性和安全性都够。有些新教程推荐 ed25519，它的长度更短、速度更快，但如果你的运维环境或者旧服务器不支持，反而会出问题。生产环境我建议保守一点，rsa 4096。

第二步，复制公钥内容：

bash复制cat ~/.ssh/id_rsa.pub

终端会显示一串 ssh-rsa AAAA... 开头的长文本，从 ssh-rsa 一直复制到末尾的邮箱地址，全部选中，一个字符都不能少。

第三步，添加到Gitee：

登录Gitee网页端，点击右上角头像，进入“设置” -> “安全设置” -> “SSH公钥”。标题随便填一个，比如“MacBook Pro”，公钥粘贴进文本框，点击确定。

第四步，测试连接：

bash复制ssh -T git@gitee.com

首次执行会提示是否确认连接，输入 yes 回车。如果配置成功，终端会返回类似“Hi 你的用户名! You've successfully authenticated...”的提示。

3.3 把已有的HTTPS远程地址改成SSH

如果你之前已经用HTTPS方式克隆了仓库，想免密，不需要重新clone，只需修改远程地址：

bash复制git remote set-url origin git@gitee.com:USERNAME/REPO.git

修改后执行 git remote -v 查看，确认地址已经变成SSH格式即可。

如果测试不成功，排查看下面几个地方：

公钥是否完整复制，有没有漏掉末尾的 “==”；
私钥文件权限是否过高，chmod 600 ~/.ssh/id_rsa 是基本要求；
是否用了非默认路径的密钥，需要在 ~/.ssh/config 里加一条Host配置。

我踩过一个坑：在同一台机器上同时使用Gitee和公司的私有GitLab，两个平台用了不同的密钥对，结果Gitee能用、GitLab连接不上。后来在 ~/.ssh/config 里做了分流：

bash复制Host gitee.com
  HostName gitee.com
  User git
  IdentityFile ~/.ssh/id_rsa_gitee

Host gitlab.company.com
  HostName gitlab.company.com
  User git
  IdentityFile ~/.ssh/id_rsa_gitlab

之后再没出过密钥冲突。

4. Gitee Pages：用仓库托管网页的正解

4.1 “Gitee Pages没有了吗”背后的真相

“Gitee Pages 没有了吗”这个疑问，在开发者社区里反复出现过，每次都能引起一波讨论。事情的背景是，Gitee Pages免费服务确实经历过一段调整期，审核规则变得严格，一度让人以为功能要被砍掉。

实际情况是：Gitee Pages现在依然可以正常使用，但门槛变了。具体来说，需要实名认证，且博客内容需要符合平台的内容审核规范。另外，部署的仓库不能是纯空壳，需要有实际可访问的静态页面文件。这个功能对个人建站、项目演示、开源项目文档托管来说依然是很好用的。

如果你准备部署一个静态博客，以下是我验证过多次的完整流程。

4.2 用Gitee Pages部署静态博客（实操全过程）

第一步，确认你的仓库有一个静态网站入口文件。 最简单的情况，仓库根目录下至少有一个 index.html。如果你用的是Hexo、VuePress这类静态站点生成器，提前执行构建命令，把生成的 public 或 docs/.vitepress/dist 目录内容准备好。

第二步，进入仓库页面，点击“服务”选项卡，选择“Gitee Pages”。

第三步，配置部署信息：

部署分支：选择你要发布的分支，一般是 master 或 main；
部署目录：如果静态文件在仓库根目录，填 /；如果在子目录，比如 docs/，填 docs；
强制HTTPS：建议勾选，浏览器不会报不安全警告；
自定义域名：如果有域名，按照提示解析到Gitee Pages提供的CNAME地址。

第四步，点击“启动部署”。 系统会执行一次构建，通常几十秒内完成。部署成功后，页面会给出一个默认的访问地址，格式是 https://你的用户名.gitee.io/仓库名。

如果你用的是VuePress这类工具，部署目录通常要填 docs/.vuepress/dist，不要填成 docs。填错的话，部署出来大概率是404或者目录结构错乱。

4.3 更新内容后为什么要手动重新部署

Gitee Pages和GitHub Pages有一个显著区别：GitHub Pages在代码推送后自动触发构建，Gitee Pages需要你回到Pages服务页面，点击“更新”按钮手动触发部署。

我第一次用Gitee Pages时没注意这点，改了文章用 git push 推到仓库，以为线上会自动刷新。结果刷新浏览器，内容纹丝不动，排查了大半天，最后发现是少了一步手动更新。这个机制说不上好或坏，但对于访问量不大、更新不频繁的个人博客来说，影响很小，养成“推完代码就顺手点一次更新”的习惯即可。

如果点击更新后提示审核不通过，多半是页面里有违规内容——比如爬虫类教程、破解资源下载、敏感时政内容等。处理方法就是把相关页面从网站中移除，重新推送再点更新。Gitee Pages面向国内用户，内容合规是硬底线，这个没什么讨论空间。

5. 开源许可证怎么选：一个容易被忽略的痛点

5.1 为什么许可证很重要

很多个人开发者上传开源项目时，会在仓库初始化页面看到“选择许可证”的选项，多数人直接跳过，或者随便选一个MIT就完事。我当年也犯过这个错误——项目发布了，别人拿来商用，代码被闭源整合进商业产品，我一点办法都没有。开源不代表“放弃版权”，而是在特定许可条款下开放使用权利，选错许可证，等同于自动放弃了对自己代码的控制权。

许可证决定了别人能用你的代码做什么、不能做什么。选对了，既能保护自己，又能推动项目生态发展；选错了，要么把自己的劳动成果白送出去，要么因为授权过严导致没人敢用。

5.2 主流许可证对比与选择建议

Gitee上最常出现的许可证有四种，我把核心差异整理成下面的表格：

许可证	商用	修改后闭源	派生作品许可	典型项目	适合场景
MIT	允许	允许	宽松	jQuery、React生态很多工具库	个人开源、工具类库、希望最大程度传播
Apache-2.0	允许	允许	宽松	Kubernetes、Spring	需要专利保护声明、企业级项目
GPL-3.0	允许	禁止	必须同样GPL	Linux内核、Git	防止代码被闭源商用、偏执型开源
BSD-3-Clause	允许	允许	宽松	Nginx	与MIT类似，强调尊重原作者署名

选择建议如下：

只是想分享代码、让更多人用：选MIT，条款最短，用户没有理解成本；
企业后端项目、框架级项目：选Apache-2.0，附带明确专利授权，对商用友好，同时保留免责条款；
不希望别人把你的代码闭源后拿去卖钱：选GPL-3.0，任何基于它的分布式修改版本必须同样开源；
学校项目、科研项目：选BSD-3-Clause，和MIT类似，只是对署名描述更正式。

5.3 选许可证前先想清楚这三件事

第一件事，你的项目里有没有“别人的代码”。 如果你的代码依赖某个GPL项目，你的项目也必须换用GPL许可证，否则法律上不成立。反过来，如果只是用了一个MIT库，那你选什么都不受影响。

第二件事，文档、图片、音源素材和代码许可证要区分开。 Gitee仓库里往往不止有代码，还有博客文章、项目截图、字体、音效等。代码可以走MIT，文章和图片可以走知识共享（CC BY 4.0），音源素材可能涉及第三方版权。建议在项目根目录放一个 LICENSE 文件说明主许可证，再放一个 NOTICE 或 README 段落说明素材部分的授权情况。

第三件事，选完许可证后要在文件头标注。 每个源文件顶部加上许可证声明，格式如下：

text复制/*
 * Copyright (c) 2024 你的名字
 * SPDX-License-Identifier: MIT
 */

这样别人复制代码时，授权信息会跟着走，不会因为文件被挪到其他项目里而失去来源。

6. 高频问题排查：从clone报错到Issue验证码

6.1 拉取项目到本地的基本操作

无论是从Gitee拉取自己的仓库，还是克隆别人的开源项目，基本命令就一个：

bash复制git clone https://gitee.com/USERNAME/REPO.git

如果你已经配置了SSH Key，且远程地址是SSH格式，用：

bash复制git clone git@gitee.com:USERNAME/REPO.git

克隆完成后进入项目目录，日常同步用 git pull 拉取远程更新。如果你是团队协作者，且本地有未提交的改动，git pull 可能会提示冲突，这时候需要先处理冲突再提交，不能强制覆盖。

6.2 clone报错 “git did not exit cleanly”

这是一个非常典型的Gitee用户问题，报错信息长这样：

text复制error: RPC failed; HTTP 500 curl 22 The requested URL returned error: 500
fatal: the remote end hung up unexpectedly

或是在TortoiseGit等图形化工具里直接弹窗提示 “git did not exit cleanly (code 128)”。

遇到这个问题，按下面的顺序排查：

第一步，检查路径中是否包含中文或空格。 这是最容易被忽视的原因。Windows下很多用户的用户名是中文，项目文件路径还有空格，Git的某些版本在中文路径下会闹脾气。解决办法是把仓库放到纯英文路径目录下，比如 D:\projects\my-repo，再试一次。

第二步，检查网络代理设置。 Git操作走代理，代理服务器地址不对或端口不通，远程连接会直接失败。查看全局配置：

bash复制git config --global --list

看到 http.proxy 相关配置就先记下来，然后临时取消：

bash复制git config --global --unset http.proxy
git config --global --unset https.proxy

第三步，调整HTTP缓存大小。 克隆大仓库时，默认的HTTP缓冲区不够大，容易中断。加大缓存再试：

bash复制git config --global http.postBuffer 524288000

这个值单位是字节，上面设置的是500MB。改完后重新clone，大部分情况下能解决。

6.3 分支命名规范：团队协作的“交通规则”

分支命名看上去是个小事，实际影响很大。没有规范的分支名，代码仓库会变成一团乱麻。我建议团队统一使用下面的命名模式：

分支类型	命名格式	示例
主分支	master/main	master
开发分支	develop	develop
功能分支	feature/功能描述	feature/user-login
修复分支	fix/问题描述	fix/cart-price-error
发布分支	release/版本号	release/1.2.0
紧急性修复	hotfix/问题描述	hotfix/login-error

新功能的开发流程一般是：从 develop 切出 feature/user-login，开发完成后合并回 develop，测试稳定后再从 develop 切出 release/1.2.0 做发版准备。这个模型叫Git Flow，团队稍具规模后就该执行，不要等到仓库乱到不可收拾才治理。

6.4 创建Issue验证码错误：浏览器环境与安全插件

在Gitee上创建Issue时，偶尔会遇到验证码显示不出来或者输入正确也提示错误的情况。这类问题90%以上出在浏览器端，不是账号或者平台的锅。

最常遇到的情况是这类原因：

浏览器广告拦截插件把验证码脚本拦掉了，解决办法是暂时禁用拦截插件，或把 gitee.com 加入白名单；
浏览器缓存了旧的验证码状态，按 Ctrl+F5 强制刷新，或者换一个无痕窗口；
浏览器自动填充干扰，Chrome等浏览器有时会把密码管理器的内容填充到验证码框，导致数据错乱，关掉该网站的自动填充再试；
脚本未加载完整，慢网络下验证码组件加载到一半就提交，会出现“验证码错误”的假报错，等页面右下角加载状态完全停止再操作。

如果上述方法都不行，换个设备（比如从电脑换到手机）试一下，基本能绕过。

6.5 如何把Gitee上的小程序项目拉到微信开发者工具

这个场景是微信小程序开发中很常见的操作。团队把小程序源码放在Gitee仓库管理，之后用微信开发者工具打开这个项目进行调试。步骤如下：

第一种方式，通过微信开发者工具直接导入：

本地先把Gitee仓库clone到工作目录；
打开微信开发者工具，点击“导入项目”；
目录选择你clone下来的项目文件夹；
AppID：如果你没有注册小程序，选择“测试号”即可；
点击确定，工具会识别项目内的 project.config.json，加载完成后就能看到模拟器预览。

第二种方式，用开发者工具拉起仓库创建：

微信开发者工具新版本支持“从代码仓库拉取”的功能。选择“新建项目” -> “从外部仓库拉取”，填入Gitee仓库的HTTPS地址，工具会自动执行克隆逻辑，但需要输入Gitee账号密码。

这里有一个经验：微信开发者工具的Git集成比较基础，遇到分支切换和文件冲突时体验一般。 稳妥的做法是：用微信开发者工具只做预览调试，不用它的内置Git功能，所有Git操作在命令行或VSCode里完成，开发工具只负责“打开项目”。

7. 热词背后的真实场景：资源分发与学习生态

7.1 游戏包、音源合集：Gitee成了“资源中转站”

热搜词里有“生存战争gitee”和“gitee音源合集”，说明很多人把Gitee当作资源分发渠道了。这类需求通常是这样：某个游戏玩家做了一个生存类地图或Mod，源码不大，打包后几十MB，想分享给社区下载；或者某个虚拟歌手爱好者把采集的音源预处理脚本整理成合集，需要同步更新和版本管理。

Gitee在轻量级资源分发场景下确实很好用——不限制仓库数量，单个仓库对常见格式支持足够，而且国内下载速度快。但要注意两个边界：

一是单个大文件的限制。 Gitee仓库对单文件大小有限制，超过一定大小（通常100MB级别）会报错，不适合放游戏安装包这种动辄几个GB的资源。解决思路是：大型二进制资源放对象存储或网盘，Gitee仓库只放安装指南和校验和脚本。

二是版权合规。 分享音源、游戏Mod时必须确认有分发授权。没有授权的素材合集一旦被投诉，仓库会被关闭。不要抱有侥幸心理，版权方跨平台举报是常态。

7.2 环境安装脚本：Gitee上的“一键开局”

热搜词还有一个“下期视频更新桌面环境的安装 gitee:https://gitee.com/hgn977/install-kali-on”，这个仓库的性质是“环境安装脚本指引”。很多技术博主和课程作者会把Kali等系统的安装脚本、配置步骤、踩坑记录整理到Gitee仓库，并在B站视频下方放上“配套代码仓库”，形成“视频 + 仓库文档 + 可执行脚本”的组合内容生态。

这种做法我认为是效率很高的技术分享方式。视频适合演示过程，文档适合查细节，脚本适合直接复用。三者通过一个Gitee仓库关联起来，学习者可以按需取用，博主也能持续更新修正，比在视频简介里放一串网盘地址要规范得多。如果你也在做技术教程类的分享，强烈建议建一个配套仓库，按章节或工具分类，这样别人收藏你的视频，其实是在收藏你的仓库。

7.3 个人开源与求职作品集：Gitee的长期价值

对开发者个人来说，Gitee还有一个隐形价值——求职作品集。现在很多技术面试官在简历上看到项目经历，都会顺手要求“提供一下代码仓库地址”。如果你的项目托管在Gitee，面试官点开就能看到代码质量、提交记录、README文档、分支管理是否规范。这些信息比简历里五行技术栈描述真实得多。

建议个人开发者至少维护两个代表性项目：一个是能体现技术深度的项目（比如自研的小框架、中间件、复杂的业务系统），另一个是能体现工程习惯的项目（比如规范化的多分支协作、完善的CI配置、清晰的中文文档）。这两个项目放在个人主页上，比任何“自我评价”都更有说服力。

8. 从“能用”到“好用”：我看到的Gitee实际状态

写这篇文章时，我特意看了下Gitee近两年的更新节奏，它不只在做“国产替代”，也在做很多独立的功能创新。比如Gitee Go这套CI/CD能力，虽然没有大厂云效、CodePipeline那么重，但对中小团队来说完全够用；再比如它的人工智能代码评审能力上线后，团队评审一些常规改动时，机器先过一遍，再人工评审，效率高出不少。

在实际使用感受上，有几个细节值得肯定：

国内访问速度快，git clone 大仓库时在网络高峰期基本不会断流，这对国内团队是最核心的体验；
中文文档和社区问答完善，遇到问题直接搜Gitee官方帮助中心，大部分都有现成的解法；
开源项目扶持计划给一些优质项目提供了实际资源，个人开发者可以关注一下。

当然也有劝退的点。Gitee Pages手动部署机制对自动化要求高的用户不太友好；仓库容量和个人版的流水线执行时长有一些限制，这些在大规模商业团队里可能会成为瓶颈。但如果你是想找一个国内可用、规范可靠、能支撑从个人学习到企业级研发流程的代码托管平台，Gitee目前还是第一梯队的选择。

最后分享一个我自己的习惯：我会在Gitee上同时维护两类仓库——一类是给团队和社区看的正式项目，分支规范、提交信息工整、文档完整；另一类是随手记录的学习笔记和实验代码，允许混乱、允许跳跃、允许中途放弃。前者用来做严谨的交付，后者用来做自由的探索。这个习惯让我在使用Gitee时既保持专业性，又不用背着“每个仓库都必须完美”的压力。如果你刚开始用Gitee，不妨也这样试试。