2025年再聊 Gitee已经不是一个简单的“国内 Git 托管”话题。你会发现它正慢慢长成一套完整的研发基础设施代码仓库、Pages 站点、CI/CD、开源许可证引导、甚至 AI 代码辅助都塞进了同一个平台里。这篇文章不打算做成官方文档的复读机而是从一个普通开发者的角度把这一年里我在 Gitee 上反复用到的功能、踩过的坑以及关于本土化生态的观察一次性说清楚。无论是刚接触 Git 的新手还是准备开源项目的维护者应该都能拿走一些立刻能用的东西。1. Gitee 生态定位与本土化优势1.1 国内开发者为什么需要一个“本土代码平台”Gitee 从 2013 年上线到现在产品定位已经换了好几轮。说实话早年它更多被人当成“国际代码托管平台的备胎”但到了 2025 年这个印象已经站不住了。国内团队在使用全球平台时总会遇到几个现实问题文档和 issue 交流用中文更顺畅代码评审里夹杂着大量母语描述时效率完全不同服务器路径远导致 clone 和 push 的体感速度不稳定核心维护者大多在国内时区提了 issue 希望当天就能得到回应不想隔着一个昼夜等回复。再加上企业对代码资产留在境内、满足合规审计的要求越来越普遍一个真正服务本地开发者的平台就成了刚需。Gitee 正好填了这个空位。它把项目托管、代码评审、问题追踪、CI/CD 都做成了统一账号体系开源项目有专门的开源社区频道企业项目有独立的企业版空间。本土化不仅仅是语言而是围绕国内开发者的习惯去设计流程。比如说 Gitee 的 PR 流程比很多海外平台更贴近中文团队的协作方式开发者可以按模块指派、一键合并界面也没有太多冗余概念。我个人的体验是带领新人入门时在 Gitee 上做 Code Review 的沟通成本明显更低大家不用先去弄懂一堆专业英文术语直接就能把注意力放在代码本身。1.2 2025 年 Gitee 的产品矩阵变化也许有人觉得 Gitee 不就是个仓库托管吗其实从 2025 年的功能版图看它已经变成了一块完整的研发基础设施模块对应能力典型使用场景代码托管Git 仓库、分支保护、PR、Issue日常协作、版本管理Gitee Pages静态站点托管个人主页、开源文档、前端 DemoGitee GoCI/CD 流水线自动测试、构建、部署开源社区项目推荐、热门话题、组织号开源项目运营、技术曝光企业版私有化部署、细粒度权限、审计企业内部研发流程AI 辅助代码解释、提交信息生成、智能评审个人提效、代码审查这些功能不是简单堆砌而是“本土化突围”的体现。尤其是 Gitee Go它和仓库深度绑定你不需要再单独接入第三方 CI/CD 平台直接在仓库里配置流水线就能完成自动构建和部署。对中小企业来说这省掉的不仅是一笔费用更是运维精力。2025 年的竞争已经不是“哪个平台仓库容量更大”而是“谁能把从创建代码到上线运行的整条链路做顺”。Gitee 在这条链路里选了一个对国内团队最友好的切入点开箱即用、账号统一、合规可控。2. 高频实操从密钥配置到代码托管全流程2.1 SSH 密钥配置一次性配置长期受益网上关于“git 配置 gitee 密钥”的搜索量一直很高说明这是很多人第一次使用就会碰到的问题。用 SSH 协议访问远程仓库的最大好处是配置一次之后push 和 pull 都不需要反复输入用户名密码也比 HTTPS 传输更安全。我建议为 Gitee 单独生成一个密钥不要和 GitHub 或其他平台混用一个这样即使某台机器需要隔离权限也不会影响其他平台。第一步检查本地是否已经有密钥ls -al ~/.ssh如果没有直接生成一个新的专用密钥ssh-keygen -t ed25519 -C your_emailexample.com -f ~/.ssh/id_ed25519_gitee用 ed25519 是因为它比传统 RSA 更短、更快安全性也足够强。生成过程中会问你是否设置 passphrase也就是私钥口令建议设置一个虽然每次连接会多一次验证但私钥泄露时的损失会小很多。第二步把公钥添加到 Gitee。用文本编辑器打开~/.ssh/id_ed25519_gitee.pub复制全部内容登录 Gitee 后进入“设置 → SSH 公钥”粘贴保存。第三步配置~/.ssh/config文件避免和其他平台冲突Host gitee.com HostName gitee.com User git IdentityFile ~/.ssh/id_ed25519_gitee IdentitiesOnly yes这里的IdentitiesOnly yes非常关键它告诉 SSH 客户端只使用指定的私钥文件防止系统把同一个私钥乱用到其他平台。最后测试连接ssh -T gitgitee.com看到欢迎信息说明密钥配置成功了。如果你在公司用的是强制 RSA 环境也可以把生成命令换成ssh-keygen -t rsa -b 4096其余步骤完全一样。2.2 代码上传与下载三种方式的选型密钥配置好之后剩下的就是具体命令。Gitee 新建仓库后页面会直接给出推荐命令但很多新手并不知道这些命令背后的逻辑这里按场景拆开讲。最常见的场景是本地已经有一个项目目录需要推送到空仓库git init git remote add origin gitgitee.com:你的用户名/仓库名.git git add . git commit -m init project git push -u origin master-u参数会把本地分支和远程分支关联起来以后直接执行git push或git pull就可以不用再输入完整命令。如果你要从 Gitee 下载代码最简单的是直接点仓库页面的“克隆/下载”按钮支持 SSH、HTTPS 和 ZIP 下载。只想看看源码的话下载 ZIP 就够了想参与贡献或长期同步更新必须使用 Gitgit clone gitgitee.com:你的用户名/仓库名.git还有一种被很多人忽略的方式是 WebIDE。Gitee 仓库页面可以直接打开网页版 IDE在线修改文件、提交变更、发 PR特别适合临时改个文档或者修个拼写错误。我自己的习惯是大功能在本地开发小修改直接在 WebIDE 完成效率很高。需要提醒的是新建仓库的默认分支名可能是master也可能是main团队最好在创建仓库时就统一避免以后每次都要处理分支重命名的问题。2.3 高频报错排查我把踩过的坑都列出来用 Gitee 时间长了总会碰到一些报错。这里整理成速查表都是完全可以直接对着查的。报错信息原因解决办法Permission denied (publickey)SSH 密钥没有被 Gitee 识别确认公钥已添加到 Gitee检查~/.ssh/config是否正确Repository not found仓库不存在或没有权限检查仓库地址是否写错以及仓库是否私有Failed to push some refs远程有本地没有的提交先执行git pull --rebase再推送RPC failed; HTTP 413HTTPS 传输大文件被限制改用 SSH 传输或者使用 Git LFS文件明明重命名了但 Git 不识别Git 默认忽略大小写使用git mv来重命名文件最让我印象深刻的坑是 SSH 密钥配置完测试时依然报 Permission denied。排查了半天最后发现是~/.ssh目录权限不对把目录权限改成700、私钥改成600就好了。另外Gitee 普通仓库对单文件大小有上限不要把编译出来的二进制包直接放进仓库用 Releases 附件来分发才是正确姿势。3. Gitee Pages把项目变成可访问的站点3.1 Pages 的定位与适用场景Gitee Pages 是一个静态站点托管服务支持从仓库的指定分支或者指定目录发布页面最终会得到一个类似用户名.gitee.io的访问地址。对开发者来说这是最快速的项目展示窗口个人简历、开源项目文档、前端 Demo、产品落地页都可以用它来承载。需要明确的是Pages 只能托管静态文件不能跑 PHP、Java 这些服务端脚本但像 Hexo、VuePress、Docsify 生成的静态网站完全没问题。很多开发者会把最新版本的 VuePress 文档构建产物放到独立分支然后通过 Pages 服务对外发布项目说明和代码仓库共用同一个维护入口体验非常顺。另一个容易被忽略的点是合规要求Pages 服务部署时通常需要完成实名认证同时内容必须合法合规不满足要求的站点会被关闭。3.2 从一个 HTML 文件开始部署 Pages部署步骤并不复杂我演示一个最简单的流程。第一步新建一个公开仓库上传一个index.html内容随意只要是一份完整页面就行。第二步进入仓库页面点击左侧“服务 → Gitee Pages”。选择部署分支一般就是你仓库的默认分支目录默认根目录然后点击启动。第三步等待一两分钟系统会返回一个gitee.io的地址直接访问就能看到页面。第四步后续更新页面内容后需要回到 Pages 管理页手动点击“更新”按钮才会触发重新部署。虽然某些配置支持自动构建但手动更新更可控尤其是在多分支协作时避免把未验证内容直接发布出去。如果你用的是 VuePress 这类静态站点生成器建议把构建产物放到docs目录或者独立分支。部署分支指向那个目录或分支正文分支继续管理源码互不干扰。还要注意一个问题所有资源路径尽量用相对路径尤其当站点不是部署在域名根路径时。很多人在 Pages 上页面打开是空白打开控制台才发现是 CSS 和 JS 引用了绝对路径导致资源 404。3.3 自定义域名、HTTPS 和常见问题Gitee Pages 默认域名虽然能用但如果你想打造个人品牌绑定自己的域名会更专业。操作上先在 Pages 设置里填写自定义域名然后到你的 DNS 服务商添加一条 CNAME 记录指向 Gitee 提供的默认地址。这里有一个容易被忽略的坑一定要在仓库根目录放一个CNAME文件内容就是你的自定义域名。否则每次重新部署或者平台调整自定义域名可能被重置丢失。HTTPS 方面Gitee Pages 提供免费证书开启后可以强制通过https://访问。我碰到过证书更新有延迟的情况这时候清除浏览器缓存或者稍等片刻再访问即可不用急着找平台重置。关于 Pages 的常见问题我列几个高频的部署后 404检查部署分支名和目录是否写对很多时候是分支选错或目录多写了一层。页面样式全丢查看资源引用路径改成相对路径。一直显示部署中手动点击“更新”触发一次通常能恢复。自定义域名失效检查 DNS 是否被改动同时确认仓库根目录的CNAME文件还在。4. 开源许可证选择别让项目“裸奔”4.1 主流许可证速查MIT、Apache-2.0、GPL-3.0“Gitee 开源许可证选什么”是高频问题很多人在创建仓库时都犹豫过。其实开源许可证没有绝对标准答案只有“适不适合你的项目”。先看主流选项速查表许可证特点适合项目MIT几乎不做限制保留版权声明即可个人项目、类库、模板Apache-2.0宽松附带专利授权条款企业级开源、需要明确专利授权GPL-3.0有传染性衍生作品必须开源希望修改版也必须共享代码BSD-3-Clause宽松但禁止用作者名字做推广学术项目、大学实验室MPL-2.0文件级弱传染模块化组件、混合开源项目简单理解MIT 和 Apache-2.0 都属于“你尽管用但出事别找我”的类型区别在于 Apache 多了一层明确专利授权所以很多大企业更愿意用 Apache 协议的项目。GPL 则是“你用了我的代码你的衍生代码也得开源”这是为了保证整个生态的开放性但对商业项目来说往往意味着额外成本。4.2 根据项目形态做选择我在 Gitee 上见过太多项目代码写得挺好但许可证要么没选要么随手选了一个使用者根本不敢放心引用。选许可证不应该靠随机而是根据项目形态来定。如果你只是个人学习项目或者提供一个简单的工具库希望被广泛使用直接选 MIT 最省事。它文字最少限制最少引用你的人没有心理负担。如果你的目标是给企业客户使用Apache-2.0 是更稳妥的选择。它明确写入了专利授权条款使用者在法律层面更清楚自己的权利这也是很多基础框架项目选择 Apache-2.0 的原因。如果你做的是一个需要社区共同维护的开放产品希望所有修改都回归到社区那就选 GPL-3.0。但要注意传染性边界如果你的项目引用了 GPL 代码整个作品的发布方式可能会受影响。还有一种情况是组件库。我给团队维护的内部组件库通常选 Apache-2.0因为公司内部很多商业项目要用宽松协议能让业务侧放心集成不需要每次用法务条款。4.3 在 Gitee 上正确声明许可证选好许可证不只是创建仓库时点一下还要保证根目录有LICENSE文件这样使用者才能准确定位条款。Gitee 在新建仓库界面可以直接选择许可证模板它会自动生成一个完整 LICENSE 文件非常方便。如果项目是前后端分离的 monorepo前端用 MIT、后端用 Apache-2.0这种组合也是允许的但需要在各自目录分别放 LICENSE并在 README 里说明清楚。不要自己造“禁止商用”或者“保留所有权利”这类自定义条款它不是标准开源许可证兼容性很差使用者会因为你的一句话而不敢用你的项目。反正要么选标准协议要么干脆声明 All Rights Reserved不要搞模棱两可的中间态。5. 从个人项目到生态参与2025 年的 Gitee 玩法5.1 镜像仓库与软件分发绕不开的加速场景从最近的热搜里能看到“gitee 镜像安装 claudecode”这类需求这说明 Gitee 已经承担了“国内软件分发”的角色。很多开源工具、安装脚本、配置文件都会在 Gitee 上建立镜像仓库。比如一些 AI 编程工具国内开发者会通过 Gitee 上的镜像仓库获取安装脚本和版本说明比直接访问官方渠道的速度和稳定性都更可预期。Gitee 在这里扮演的是一个可靠的软件分发节点。如果你的项目也想让别人方便获取在 README 里同时放上 Gitee 仓库地址和 Releases 下载链接是标准做法。Releses 适合发二进制包、压缩包、安装脚本仓库本身不要堆放体积很大的文件。我见过有人把几百 MB 的数据集直接推到仓库里结果整个仓库膨胀到无法正常 clone最后还是得用 Releases 重新整理。5.2 垂直 API 聚集地小项目也能形成生态“survivalcraftapi api1.8 gitee”这样的搜索词很有意思说明一个很垂直的小众游戏开发领域已经有人在 Gitee 上维护 API 库和模组接口。这正是本土平台生态的真实样貌不一定每个项目都是千万 star但一定会有大量“小而美”的技术资源在持续更新。这些项目可能不会出现在全球技术热榜上但在 Gitee 上能被中文用户直接搜到通过 issue 快速迭代慢慢形成一个圈子。对个人开发者来说这是一个建立影响力的好机会。不用试图做一个包罗万象的巨型项目只要在一个垂直领域把某个工具做扎实自然会有人来用、来提 issue、来帮你完善文档。Gitee 的本地化社区氛围让这种反馈闭环变得很快维护者和用户之间几乎没有沟通障碍。5.3 双托管与自动化同步我的实践方案我目前维护的开源项目采用“Gitee 国际平台”双托管模式。简单来说Gitee 承担国内用户的主要互动区域issue、讨论、下载都安排在这里国际平台则保留发布记录和全球曝光。这样做的原因很实际国内用户访问体验更好国际用户也能看到项目。双托管的同步并不复杂本地仓库配置多个远程地址即可git remote add gitee gitgitee.com:用户名/仓库.git git remote add upstream gitgithub.com:用户名/仓库.git推送时分别推送到两个地址git push gitee main git push upstream main如果你有自动化需求可以写一个简单的脚本在 push 后自动同步到另一个远程。但要注意不要把任何带有密钥的配置写进脚本或者 CI 文件。Gitee 的 Gitee Go 也支持流水线你可以在每次主分支更新时自动构建并把产物部署到 Pages。我个人觉得从代码托管、文档发布到自动化部署2025 年在 Gitee 上已经可以打通一条完整的个人项目流水线了。最后说一点个人感受在 2025 年Gitee 最打动我的不是某个酷炫功能而是它真的在照顾国内开发者的使用习惯。过去我总觉得开源就要去国际社区但现在越来越多的国内项目选择先在 Gitee 上发布、积累种子用户再复制到更大舞台。如果你正准备开始第一个开源项目建议从 SSH 配置和许可证这两个基础动作开始它们不会立刻让你变强但能让你减少后面很多不必要的折腾。希望这篇记录能帮你少走一段弯路。