Gitee实战指南：从代码托管到研发流程落地的完整笔记

我见过最夸张的版本管理方式，是拿一个移动硬盘在公司里轮流拷贝代码，每次改完复制一份“带日期文件夹”。听起来像段子，但真有很多小型团队一直这么活着。直到代码冲突、交付版本不对、有人离职后代码彻底找不到，他们才开始想：是不是该上一套真正的Git托管平台了。这时候，Gitee往往就是第一个被考虑的选择。它不只是代码仓库，更是很多中国企业做数字化转型时最先落地的技术基础设施。本文我会从创建仓库、配置VSCode和IDEA、使用Gitee Pages，再到.git目录意外丢失后如何急救，结合我实际踩过的坑，给你一份可以直接照做的实战笔记。

1. 一个代码托管平台，凭什么被叫成“核心技术引擎”

1.1 企业真正需要的不是“代码网盘”，而是研发流程底座

先说结论：企业数字化这件事，代码只是表象，真正要沉淀的是流程、权限、审计、协作记录和知识库。Gitee这类平台的价值，在于把所有研发动作变成一个可追踪、可审计、可回溯的链路。比如需求从Issue里提出来，关联到某个分支，开发完提交Pull Request，评审人留下评论，CI跑完构建，再合并到主分支，最后打Tag发布。这一整条链路如果在Gitee上完整跑起来，公司即便换几轮人，项目的演进过程也清清楚楚。

很多管理者第一次接触Gitee时，会把它理解成一个“放代码的地方”，让开发把代码传上去就行。但如果只做到这一步，跟移动硬盘拷贝没有本质区别。真正的转折点是：所有对代码的改动都有作者署名、都有时间戳、都有变更原因，且只有被授权的人才能操作。达到这个状态之后，代码就不仅仅是一堆文件，而是企业的数字资产。

1.2 为什么是Gitee，而不是自建Git服务

团队规模不大时，有人会想：我拿一台服务器自己装个GitLab，不也差不多？我试过这么干，结论是能用，但你得分出一个人长期维护。GitLab本身不算轻量，内存小一点的服务器跑起来卡到怀疑人生；备份、升级、漏洞修复、磁盘告警，哪一样都得有人盯。对以业务开发为主的企业团队来说，这是一笔被低估的隐性成本。

用Gitee这类托管平台，省掉的是基础设施运维，换来的是更多精力投入业务本身。我整理了一张实际选型时会关注的对比，供你做决策参考：

当然，如果是几百人以上的规模化团队，或者有强监管合规要求，选择企业版私有部署是合理的。但对于大多数中小企业和初建研发团队，先把托管平台用好，远比一开始就搭一套复杂系统更实在。

1.3 围绕“数字化转型”的落地价值

数字化转型不能只落在PPT里。我从实际观察看到，Gitee在企业里落地之后，带来的最明显改变是“信息不对称被压缩”。新人入职，不用追着同事问“项目代码在哪”，直接进仓库看README和Issue记录；管理层想了解项目进展，不用开一堆会，看提交频率和分支活跃度就有数。研发过程数据化之后，后续做效能度量、质量分析都有基础数据支撑。

2. 从创建仓库到第一次提交，动手前先把这些想清楚

2.1 创建仓库时的关键选项

在Gitee上新建仓库，界面不算复杂，但几个选项会直接影响后续使用。仓库名称建议用小写字母、数字和连字符，比如“order-service”，而不要用中文或空格，否则在Linux部署、CI脚本拼接地址时很容易出问题。路径名和仓库名保持对应关系，这里的“路径”会成为整个仓库URL的一部分，改起来后期很麻烦。

如果不确定仓库是公开还是私有，建议先从私有开始。很多团队一时上头把公司业务代码设成公开，等发现敏感信息泄露再转私有就晚了。Gitee上私有仓库只有仓库成员能访问，对于企业日常开发，这本身就是默认选择。

初始化仓库时要不要勾选README、.gitignore和开源许可证，我建议：.gitignore必须勾选，README可以先用模板，许可证则需要慎重选择。网上不少人问“Gitee开源许可证选什么”，我下面专门展开讲。

2.2 开源许可证到底怎么选

许可证的选择，本质上是回答三个问题：允许别人商用吗？允许别人修改后闭源吗？用你的代码的人需要承担什么义务？想清楚这三点，答案就浮出来了。

常见的几类许可证，我按宽松到严格排一下：

• MIT：最宽松，几乎没限制。企业内部工具、SDK示例、个人项目都可以用。别人拿了你的代码闭源商用也不用告诉你，风险最小。
• Apache-2.0：比MIT多一个专利授权和商标条款，大公司间合作比较喜欢。如果项目可能涉及专利纠纷，Apache能提供额外保护。
• GPL-3.0：要求衍生作品如果对外发布，也必须用GPL开源。适合想反哺社区、不愿意让别人闭源改造的产品。
• LGPL：主要用于库，允许动态链接闭源使用，但修改库本身要开源。
• MPL-2.0：文件级copyleft，修改过的文件要开源，其他部分可以闭源。
• AGPL：最严格，即使通过网络提供服务也算发布。如果不想别人拿你的代码跑SaaS，选AGPL。

对大多数个人开源小项目，我建议MIT或Apache-2.0；如果你的商业模式依赖闭源服务端，但你又想让社区信任，GPL/AGPL也是一种战略选择。企业内部私有仓库呢？许可证其实无所谓，因为你没准备对外发布，选什么都不重要，但建议随手选一个宽松的，免得哪天改成公开仓库时尴尬。

2.3 第一次上传代码：网页上传还是命令行

很多人第一次接触“gitee上传代码到仓库”的困惑，其实是两个概念没厘清：本地仓库和远程仓库。本地仓库就是你自己电脑上的代码目录，初始化的标志是出现一个.git目录；远程仓库是Gitee服务器上的那份存储。上传代码的本质，就是把本地提交推送到远程。

如果你只是偶尔传个文件，网页端直接拖拽上传当然可以；但做正经项目，一定要用Git命令行或编辑器集成的Git功能。常用的流程是这样：

bash复制cd your-project
git init
git remote add origin https://gitee.com/yourname/your-repo.git
git add .
git commit -m "init project"
git push -u origin master

这几条命令里容易踩坑的是分支名。Gitee默认分支可能显示为master，也可能显示为main，不同阶段创建仓库的默认值不完全一样。第一次push时最好先git branch -M master，或者直接改成你在Gitee仓库页看到的分支名，免得推送时提示远程分支不存在。

如果本地代码还没有做过任何Git操作，用上面五条就够；如果项目已经有.git目录，甚至之前在其它仓库下，就只用改remote地址：

bash复制git remote set-url origin https://gitee.com/yourname/new-repo.git
git push -u origin master

2.4 .gitignore为什么说啥都要配

我在新仓库里见到的第一种“脏乱差”，就是没有.gitignore，导致node_modules、target、build、.idea这些目录全部进了仓库。后果不只是仓库体积膨胀，代码评审里会刷出一堆无意义的文件变更，严重时甚至把本地配置、密钥文件一并提交上去，这在企业内部合规审计中是重大隐患。

Gitee创建仓库时会在模板列表里提供常见语言的.gitignore，建议创建仓库时就勾上。如果你已经创建完仓库，也可以后补：

bash复制touch .gitignore
# 写入需要忽略的文件和目录，比如：
# /node_modules
# /target
# /.idea
# *.log
git rm -r --cached .
git add .
git commit -m "chore: add gitignore"
git push

注意git rm -r --cached .的作用是把已跟踪的文件从Git索引里移除，但不会删除你本地文件。执行完再重新add，Git就会按新的.gitignore规则重新计算要跟踪的文件。

2.5 仓库改名或换地址后，本地怎么跟上

企业重组、产品更名、仓库从个人账号转给组织，都会导致仓库地址变化。这时候本地代码里记录的remote还是旧地址，push时会一脸懵。用一行命令改回来：

bash复制git remote -v
git remote set-url origin 新的仓库地址
git push

如果项目已经在别的机器上克隆过，也按同样方式更新。这个问题挺多人遇到，尤其在“gitee仓库如何创建”“idea怎么连接gitee仓库”这类操作之后，因为各个环节的工具配置的都是旧地址。

3. VSCode和IDEA两端的Gitee日常操作，以及我踩过的坑

3.1 VSCode配置Gitee：卡在“Access denied”怎么办

VSCode里操作Gitee，需要先把本机Git装好。装好之后，打开VSCode，在扩展市场搜索“Git”相关插件，官方自带的Git功能其实已经够用，额外装Gitee扩展更多是为了方便浏览Issues和Pull Request。关键的一步在账号凭据配置。

早期版本支持直接输入密码，后来出于安全考虑，平台普遍要求使用私人令牌。在VSCode里push时如果提示HTTP Basic: Access denied，十有八九是凭据问题。去Gitee个人设置里生成一个私人令牌，勾选projects、user等需要的权限，把生成的令牌作为密码输入即可。注意令牌只显示一次，记得赶紧复制保存。

我在实际使用中还遇到一个隐藏问题：VSCode配置的远端URL是https地址，推送到大仓库时频繁超时。后来把.git里的remote地址改成基于SSH的格式，明显稳定很多。SSH方式需要在Gitee后台添加本机公钥，步骤如下：

bash复制ssh-keygen -t rsa -b 4096 -C "你的邮箱"
cat ~/.ssh/id_rsa.pub

把输出的公钥复制到Gitee的“SSH公钥管理”里，保存后再把remote地址换成git@gitee.com:用户名/仓库名.git。这样VSCode和命令行工具都能用同一套SSH身份访问，省心不少。

3.2 IDEA连接Gitee并运行下载的项目

“gitee下载的代码怎么在idea运行”这个问题，基本每个转Java开发的都问过。先说从Gitee克隆项目到IDEA的路径：第一次打开IDEA，选择Get from VCS，把Gitee仓库的URL粘贴进去，克隆完成后IDEA会自动识别构建工具。

对Maven项目，IDEA会弹窗提示加载Maven工程，选择信任项目后等待依赖下载完成，然后配置好JDK和Maven环境，找到启动类运行。Gradle项目类似，但注意Gradle版本与JDK要匹配，IDEA自动下载Gradle时经常因为网络超时失败，最好在本地配置好Gradle并指定使用本地版本。

如果项目已经下载成ZIP解压到本地，不想用Git方式打开，File → New → Project from Existing Sources，选中项目目录，IDEA也能按Maven/Gradle工程导入。但这种方式导入的目录通常没有.git关联，之后的代码提交推送功能用不了。正确的做法还是先克隆，保持Git关联。

3.3 跨编辑器协作时的三个小坑

一个团队里总有同事用VSCode，有人用IDEA，代码在Gitee上协同，最常见的坑有三个：

• 行尾不一致：Windows默认CRLF，Linux和macOS默认LF。如果.gitattributes没配好，每次pull都会提示全文件变更。建议仓库根目录建.gitattributes，把* text=auto eol=lf写进去，让Git统一处理。
• 编码问题：IDEA和VSCode都默认UTF-8时问题不大，但Windows上如果系统区域设置影响默认编码，偶尔会出现GBK乱码。建议在各级配置文件里显式设置UTF-8，而不是依赖系统默认。
• 提交者身份混乱：有些同事的Git全局user.name是“user”，user.email是乱填的，push之后Gitee贡献图和时间线就乱了。可以在仓库里执行git config user.name "真实姓名"和git config user.email "公司邮箱"，强制每个仓库使用统一身份。

4. Gitee Pages的现状与正确打开方式

4.1 先回答“Gitee Pages是不是没有了”

网上一直有人说“gitee pages没有了吗”，我也专门回过这个疑问。Gitee Pages服务在多数时间是可以正常开通的，只是它的开通有一定条件：账号需要完成实名认证；如果你是免费用户，部分时段或不同网络环境下的访问可能不稳定；服务规则也在收紧，域名更换、HTTPS证书配置都要在后台重新操作。

之所以总有人问“没有了”，可能是因为部署成功后访问域名被拦截、网页显示限制访问，或者用户不清楚Pages的审核机制。这里我建议把它当“半托管”来理解：源码仓库放代码，Pages直接发布仓库里的静态文件，但内容审核是由平台执行的。

4.2 配置Gitee Pages的完整步骤

创建一个仓库，把静态网页文件放进去，比如index.html。仓库里可以没有代码，甚至只有一个简单的首页，Pages也能运行。接着在仓库页面找到“服务”菜单下的“Gitee Pages”，首次使用会引导你完成实名认证与域名绑定。部署时选择部署分支和目录，一般就是仓库根目录。点击启动，平台会生成一个形如你的用户名.gitee.io的地址。

更新网站内容时，光把新文件push到仓库还不够，很多人在这卡住。Pages服务默认不会自动重建，需要你手动到Pages控制台点一下更新，或者启用“自动更新”功能，之后每次push到部署分支，平台才会重新生成静态站点。如果启用了自动更新，文件生效有几分钟延迟，不要一push完就急着反复刷新页面。

4.3 真实案例：用Pages搭团队官网踩的三个坑

我之前用Gitee Pages帮一个技术小组搭过官网，选的是Hugo静态博客方案，构建出来的文件直接部署。过程本身不算复杂，但坑也不少。

第一个坑是自定义域名。配置域名后要在域名解析商那边添加CNAME记录，才能指向Gitee Pages分配的地址。如果你直接在Gitee后台填了域名但DNS解析没配，页面会一直报“No such host”。填完之后，还需要在仓库根目录放一个CNAME文件，里面写你的自定义域名，两处都要保持一致，否则部署一次就掉一次，需要重新绑定。

第二个坑是资源路径。Hugo默认会把静态资源路径写成绝对路径/xxx.css，部署到Gitee Pages的子路径时全站样式丢失。解决方法是baseURL改成子路径，并开启相对路径选项。如果你用纯HTML写死路径，部署到非根目录一样会遇到这个问题。

第三个坑是免费版没有HTTPS自动证书。平台要求你在后台根据提示配置，或提供自己的证书。如果是个人作品或团队内页，先用默认域名，不必急着上自定义域名和HTTPS。

4.4 如果Pages不满足，可以这样过渡

Pages适合展示型网站和轻量前端演示。真正要做企业官网、带后端接口的业务系统，直接上云服务器或对象存储更合适。很多对象存储服务支持静态网站托管，上传完文件就能获得一个公网链接，也支持绑定域名和HTTPS证书，比Pages灵活得多。把“静态页面”这一层抽象出来想，Pages只是把静态文件放在了一个受管环境里，你完全可以用任何能放静态文件的方案替换。

5. 本地仓库急救记录：.git丢失后如何重新绑回Gitee

5.1 事故现场：.git目录怎么就没的

“本地项目不小心把.git文件删除了，怎么重新绑定到gitee已有项目中”，这是很多搜索热词背后的真实场景。.git是Git仓库的元数据目录，里面保存着历史提交、分支、标签和远程地址。如果你不小心删了它，或者把项目当普通文件夹复制时只复制了源码，这个目录就这样没了。代码好在还在，但Git“记忆”被清空了，你跟Gitee的绑定关系自然也没了。

还有一个常见场景是项目从别的机器拷贝过来，拷的人不知道要带.git目录，于是到了新机器上，新目录里只有源码。打开IDEA能看见代码，但Git集成面板空荡荡的，pull和push都不可用。

5.2 急救第一步：判断你还有没有历史记录可以捞

如果远程Gitee仓库还活着，先别慌，你完全可以从远程把历史提交拉回来。到Gitee仓库首页复制仓库地址，在本地目录里执行：

bash复制cd your-project
git init
git remote add origin 你的仓库地址
git fetch origin
git checkout -b master --track origin/master

第一步是重新初始化一个本地仓库；第二步绑定远端；第三步是关键。git fetch origin会从远端把所有分支和提交记录拉到本地，但此时工作区还是旧状态，你的源码没有被覆盖；最后一条命令是创建一个跟踪远端分支的新本地分支，这样本地代码就会和Gitee仓库的分支建立关联。如果远端默认分支叫main，把命令里的master换成main即可。

如果远程仓库确实已经不存在了，那历史提交只能靠本地恢复。先看看有没有备份，没有的话必须承认一个事实：从Git层面捞回历史已经没有希望，因为你本地已经没有.git，提交对象全部丢失。此时能做的只是把现有源码作为“新起点”，重新init，再推送到一个新建的仓库。

5.3 急救第二步：本地代码状态太乱，先整理干净再救

有些场景下，你是先发现.git丢了，之后又顺手改了十几个文件，整个目录状态特别乱。这时候不要贸然git add .，先做一次文件盘点，把该忽略的node_modules、target全写进.gitignore，再决定哪些文件进仓库。如果原先仓库里有些文件不该推上去，新建.gitignore之后用git rm -r --cached .清理索引，再重新提交。

我的习惯是：每次急救恢复关联之前，先复制一个源码备份目录。这样即使操作中途把现有目录搞乱，还能回退到备份状态。备份目录可以放在本机其他位置，不要放进仓库内部，否则Git会把你备份的历史副本也纳入版本控制，越推越大。

5.4 换个场景：不是丢了.git，是想“移库换址”

另一类用户经常把“重新绑定”和“迁移仓库”混着说。比如公司要换Gitee组织，旧仓库要废弃，但本地代码还想保留现在的分支和提交历史。这个不用删.git，只需要做两件事：

bash复制git remote set-url origin 新仓库地址
git push -u origin --all
git push -u origin --tags

--all推送所有分支，--tags推送所有标签。之后新仓库就拥有了和老仓库完全一致的提交历史。此时再去Gitee后台把旧仓库成员、WebHook之类的配置拷到新仓库即可。这种做法是保留历史的常规操作路径。

5.5 最好用的“急救”其实是预防

经历过一次.git丢失之后，我把本地Git仓库的保护动作固化成了三条：

• 每天至少push一次工作分支到Gitee，代码只要到了远端，本地再丢都不怕。
• 重要标签和Release在Gitee后台打，不依赖本地Tag。
• 清理磁盘、迁移项目时，看清楚哪个是.git目录哪个是源码目录，不要图省事直接删。

很多团队临时找U盘拷代码，就是因为没有养成“随时推进远端”的习惯。等出事再急救，虽然能救，但过程总归是痛苦的。

6. 从“能传代码”到“数字化资产沉淀”，Gitee还可以这么用

6.1 分支模型定了，研发节奏才稳

我见过不少团队用Gitee，所有人都在master上提交，代码冲突一天到晚。问题不在Git，在于没有一个适合团队现状的分支模型。对中小团队，我建议先跑一种不复杂的模型：master作为可发布主线，develop作为开发集成线，每个人基于develop切feature分支，开发完成后发起Pull Request合回develop，准备发版时再从develop合到master并打Tag。规则不多，但能把“谁能动主干”这个问题管理住。

6.2 Pull Request不是流程负担，是质量闸门

直接把代码推到主干，省事，但如果项目不止一个人，副作用就会被放大。一次未经评审的改动可能带进去一个低级Bug，或者把临时调试代码、本机路径悄悄推到主干。在Gitee上开一个PR，意味着至少有一个成员看过这次变更，知道这里改了啥、为什么改。这个“知道”本身就是质量保障。

很多新人不理解“为什么要走PR”，我的解释是：PR记录的是“变更的理由和过程”，而commit记录的是“变更的结果”。出了线上事故时，排查者最想看到的不是最后一次commit，而是整个变更被讨论、被评审、被修改过的脉络。

6.3 成员角色、权限和审计，企业版才有底气的部分

Gitee组织里，成员角色通常分为Owner、Master、Developer和Reporter几类。Owner管组织全局，Master管仓库配置，Developer日常提交代码，Reporter只读。企业内部不要人人都是Owner，哪怕团队只有五个人，也要把权限收一收。不然哪天有人误删仓库或改掉保护分支规则，你连撤回的余地都没有。

操作日志这件事，平时感觉不到存在，等出问题后就成了救命稻草。谁在什么时间点推送过代码、谁修改了仓库设置、谁移除了成员，这些在企业规范化管理里都是硬需求。托管平台天然记录这些数据，比你自建Git服务自己写审计脚本要可靠得多。

6.4 用WebHook和CI把人工重复动作取消掉

团队小的时候，构建、部署、通知都可以靠人工，但规模稍大就撑不住了。Gitee支持WebHook，能在push、PR等事件发生时把消息推送到你的服务器或即时通讯机器人。我在团队里用它做了两个很实用的自动化：一是push到develop分支后自动触发测试环境构建，二是PR被合并后自动给群通知并附上变更摘要。代码量不大，但每天省下的等待和沟通时间非常可观。

更完整的CI/CD可以看Gitee内置的流水线能力，或者把WebHook接到外部CI系统。核心思路是：一切有规律、要重复执行的研发动作，都值得让工具自动跑，Gitee负责把“事件”这一环打通就行。

6.5 文档、Issue和Wiki，让代码周边知识也留在平台里

仓库旁边最好配一份像样的README：写清楚项目是干什么的、怎么跑起来、目录结构如何、部署需要注意什么。再配合Issue管理需求、Bug和讨论，Gitee就会逐渐从“代码托管工具”升级成“项目协作平台”。我在新团队落地Gitee时，先要求所有仓库补README，Issue模板统一格式。前几次迭代改动之后，团队自己都会感叹：终于不用到处翻聊天记录找需求背景了。

这其实就是数字化转型真正发生的地方：把散落在个人脑子和聊天工具里的信息，结构化地沉淀到团队公共平台上。

6.6 仓库里能不能放音源、图片等大文件

热词里有一条“gitee音源合集”，我猜测是有人把音源素材托管到Gitee仓库里做分享。这里要提醒一句：Git仓库不适合存大量二进制大文件。音频、视频、设计稿这些文件每次修改都会生成新版本，仓库体积会迅速膨胀，clone时间和磁盘占用都受不了。建议要么用Gitee Releases上传附件的形式管理素材包，要么用Git LFS这样的扩展机制跟踪大文件；如果只是需要下载链接，也可以改用对象存储。

如果你的“音源合集”是几首小体积文件，用仓库管理问题不大，但依然要留意仓库容量限制。平台对单仓库体积是有约束的，超过合理规模后push会失败，这时再清理历史就很折腾。

7. 写在最后

我始终觉得，工具本身不产生价值，把它用起来并坚持一段时间，才会产生价值。Gitee对公司数字化转型的贡献，并不是它能存多少行代码，而是它逼着团队把“改了什么”“谁改的”“为什么改”这几个问题说清楚。推荐你从这周就开始做一件小事：把团队里最重要的那个项目的master分支设成保护分支，要求所有代码必须通过Pull Request合入。这个动作可能带来一点不适应，但撑过两个迭代之后，你会明显感到代码质量、回溯效率和新同事的融入速度都不一样了。我个人用Gitee这几年，最深的体感就是：当项目里每个人都能独立提交、代码自动构建、文档沉淀在仓库旁边，这支团队才算真正开始了数字化转型的第一步。