蓝盐泳池1983最近这几年，国内团队做研发管理，绕不开一个名字：Gitee。可能有人觉得它只是“中国版 GitHub”，但实际用下来，你会发现它远不止一个代码仓库那么简单。从代码托管、分支管理、Issue 跟踪，到 Pages 静态页面托管和开源许可证配置，它其实承担了企业数字化转型中“研发基础设施”的角色。这篇文章我就以实际使用的视角，把 Gitee 从建仓到日常协作、从免密推送到问题排查的完整链路拆一遍，既讲操作步骤，也讲背后的逻辑和踩过的坑，希望对正在选型或者刚开始用 Gitee 的团队有帮助。
1. 为什么是 Gitee：企业数字化协同的底层逻辑
1.1 从“代码仓库”到“研发管理平台”
先聊一个容易被忽略的问题：很多团队选择 Gitee，第一反应是“因为它在国内，访问快”。这个理由没错，但它远远低估了 Gitee 在产品层面的完整度。实际使用中你会发现，Gitee 提供的核心价值不是“存代码”，而是把代码仓库、项目管理、需求跟踪、代码评审、持续集成、文档沉淀这些环节串在了一条线上。
举个例子。一个典型的数字化交付项目，通常有产品经理提需求、开发写代码、测试提 Bug、运维发版本。过去用自建 GitLab 或者飞书+Git 混搭，需求在 A 系统，代码在 B 系统，问题记录在 C 系统，三个系统之间靠人肉同步，状态经常对不上。而 Gitee 的企业空间或者团队仓库里，Issue 可以直接和 Commit 关联，提交代码时写一句 fix #123，Issue 自动流转状态；集成了 Gitee Go 之后，推送代码就能自动触发构建，状态回传仓库。这个闭环省掉的不只是来回粘贴链接的时间，更重要的是，所有信息都在一个平台上，可追溯、可审计，这对企业内部数字化的流程规范来说价值很大。
1.2 Gitee 与 GitHub、GitLab、GitEE 的定位差异
这个话题经常被拿来讨论。先说结论：GitHub、GitLab、Gitee 都是基于 Git 的开源工具或者平台，但定位完全不同。
GitHub 是全球最大的开源社区，它的优势是生态和流量，但对企业内网部署来说，它天生不合适。GitLab 是有开源版本（Community Edition）的，它解决的是“私有化部署”的问题，你可以把它装在自己的服务器上，代码不出公司，很多大中型企业内部用 GitLab 就是这个原因。Gitee 则走了一条中间路线——它既是开源社区，提供公开仓库和开源许可证管理，又有私有仓库和企业版，不需要自己运维服务器，有国内访问速度的保障。
至于前面看到的“GitEE”，实际是 Gitee 的另一种叫法，拼音展开就是 Git + Gitee（码云）。它本身就是基于 Git 的完整平台，不是某个独立工具。所以选型的核心不在这几个名字，而在于：你的代码是公开偏多还是私有偏多、需不需要自己部署服务、团队协作的上下游系统是什么。结合这些条件再去看哪个平台合适，思路就会清晰很多。
2. 从零开始：仓库创建与首次提交的完整闭环
2.1 创建仓库前必须先想清楚的三件事
很多人建仓是直接点“新建仓库”，然后一路下一步。我建议在点按钮之前，先花两分钟确认三件事，否则后患无穷。
第一，仓库可见性。Gitee 有公开仓库和私有仓库两种形态。注意，公开仓库意味着所有人都能看见你的代码，但“开源”不等于“放弃著作权”，你依然需要在仓库里放一个许可证，后面我会单独说许可证怎么选。企业内部项目，哪怕还没有商业计划，也建议先私有，等确定开源策略后再切换可见性，避免中途泄密。
第二，仓库模板。Gitee 新建仓库时提供了 .gitignore 模板和开源许可证模板。.gitignore 一定要选，尤其是你用的语言是 Java、Python、Node.js 这类编译型或者依赖型的项目，不忽略 target/、node_modules/、.env 这些目录和文件，后患无穷。.env 里经常有密钥，如果误提交到公开仓库，事情就大了。Gitee 的模板虽然不算全面，但覆盖主流语言的通用规则足够了。
第三，初始化方式。如果你选择在 Gitee 上初始化仓库（自动生成 README、许可证），那本地的新项目再推上去时，就会遇到“远程仓库已有内容，本地是空仓库”的冲突。所以我个人的建议是，新项目首次推送时，尽量在 Gitee 上建一个“空仓库”，勾选不初始化任何文件，本地再操作，这样最干净。
2.2 新项目首次推送到 Gitee 的操作步骤
这里给出我在实操中验证过多次的标准流程。假设你本地已经有一个项目目录，并且已经安装了 Git，路径是 D:/myproject。
第一步，在 Gitee 网页端创建空仓库，仓库名建议全小写加连字符，比如 order-service，不要用中文或下划线开头，避免后续命令行操作时出现编码问题。
第二步，在本地项目根目录打开终端（Windows 下我习惯用 Git Bash），执行初始化：
bash复制git init
第三步，添加远程地址。Gitee 仓库创建完成后会给出两个地址，HTTPS 和 SSH。首次推送我建议直接用 SSH 方式（免密配置在第 3 章详细说），复制仓库的 SSH 地址：
bash复制git remote add origin git@gitee.com:yourname/order-service.git
第四步，添加所有文件并提交：
bash复制git add .
git commit -m "chore: initial commit"
第一次提交的 commit message 我习惯用 chore: initial commit，语义化提交规范里 chore 表示构建或辅助工具的变更，比较符合初始化场景。
第五步，推送：
bash复制git push -u origin master
这里有个细节，-u 参数会把本地分支和远程分支建立上游关联，之后直接用 git push 就能推送，不用每次写完整命令。如果你的远程仓库默认分支是 main，就用 git push -u origin main。
如果你遇到“远程仓库已经有 README 文件导致 push 被拒绝”的情况，那只能先把远程内容拉下来合并：
bash复制git pull origin master --allow-unrelated-histories
这个参数代表允许两个没有共同提交历史的分支合并。然后重新 push 就可以了。
2.3 clone 到本地与拉取已有项目
另一个高频场景是拉取已有项目到本地。操作很简单，但要区分两种方式。
如果我只需要下载代码看一下，不打算改完再提交回去，用 HTTPS 下载 zip 包也可以，但这样没有 Git 历史和各种信息。自己参与的项目，更规范的做法是用 clone：
bash复制git clone git@gitee.com:yourname/order-service.git
这个命令会在当前目录自动创建名为 order-service 的文件夹，包含完整历史记录。克隆之后，如果你用的是 VS Code，直接打开文件夹，左下角分支图标会显示当前所在分支，右下角还能看到远程仓库的信息，非常直观。
还有一种场景：你只是临时要把某个 Gitee 上的项目拉到微信开发者工具或者某个 IDE 里运行。比如取一个开源的小程序项目，实际操作是先在微信开发者工具里选择“从代码仓库导入”，填入 Gitee 仓库的 HTTPS 地址，工具会自动识别项目类型；如果你更习惯命令行，就先用 git clone 拉到本地，再在开发者工具里选择“导入项目”，目录选刚才拉下来的文件夹即可。这里要注意的是，小程序项目 clone 下来后，要确认项目根目录有 app.json，微信开发者工具才会正确识别为小程序项目。如果打开后页面空白，大概率是导入时选错了根目录，需要在项目设置里重新指定目录。
3. 免密推送与多端配置实战
3.1 SSH keys 配置的前因后果
先说现象：用 HTTPS 方式每次 push 都要输入用户名和密码，非常打断思路。免密的思路不是“记住密码”，而是换一种身份认证方式——SSH 公钥认证。
原理很简单。你本地生成一对密钥，一个公钥、一个私钥。公钥是一把锁，放在 Gitee 账户里；私钥是一把钥匙，保存在本地。推送代码时，Gitee 用锁（公钥）来验证你有没有对应的钥匙（私钥），验证通过就直接放行，不再问密码。
配置分三步。
第一步，检查本地是否已存在 SSH 密钥：
bash复制ls ~/.ssh/id_ed25519.pub
如果提示文件不存在，就执行生成命令：
bash复制ssh-keygen -t ed25519 -C "your_email@example.com"
这里我推荐用 ed25519，比传统的 rsa 2048 更安全，生成速度也快。一路回车即可，会自动生成 id_ed25519 和 id_ed25519.pub 两个文件。
第二步，把公钥内容复制出来：
bash复制cat ~/.ssh/id_ed25519.pub
第三布，登录 Gitee，进入“设置” -> “安全设置” -> “SSH 公钥”，把内容粘贴进去，标题随便填，比如“我的Windows笔记本”。保存后验证：
bash复制ssh -T git@gitee.com
看到 “Hi xxx! You've successfully authenticated...” 的提示就成功了。之后再 push，走的就是免密通道。
3.2 一台电脑同时管理 Gitee、GitHub、GitLab
这里有一个更实际的场景：我电脑上同一时间要管理 Gitee、GitHub、甚至公司私有 GitLab 的多个仓库。如果给三个平台都生成了不同的 SSH key，不做配置的话，Git 会默认使用同一个 id_ed25519 去连接所有服务器，导致某一个平台认证失败。
解决办法是编辑 SSH 配置文件 ~/.ssh/config：
text复制Host gitee.com
HostName gitee.com
User git
IdentityFile ~/.ssh/id_ed25519_gitee
Host github.com
HostName github.com
User git
IdentityFile ~/.ssh/id_ed25519_github
Host gitlab.company.com
HostName gitlab.company.com
User git
IdentityFile ~/.ssh/id_ed25519_gitlab
这样 Git 会根据连接的域名自动选择对应的私钥。配置完成后记得用 ssh -T git@gitee.com、ssh -T git@github.com 分别验证一次。我在这里踩过一次坑：一开始只配置了 Gitee 的 key，GitHub 的仓库 push 时一直报错 Permission denied，排查了半天才发现是 SSH 共用 key 导致的。这个配置文件就是解决这个问题的标准做法。
3.3 VS Code 里的免密上传
如果你是 VS Code 用户，不用命令行推送，也可以实现免密。VS Code 的 Git 面板只是对命令行 Git 的可视化封装，所以底层还是走我们刚才配置的 SSH。也就是说，只要你在终端里用 SSH 方式 clone 了这个仓库，VS Code 里点“同步”按钮就是免密的。
有一个注意点：如果你最初是用 HTTPS 方式 clone 的仓库，哪怕你 SSH 配置好了，VS Code 推送时还是会要求输密码。解决办法是修改本仓库的远程地址：
bash复制git remote set-url origin git@gitee.com:yourname/order-service.git
改完再推送，就回到 SSH 免密通道了。这也解释了很多用户反馈的“我明明配置了 SSH，为什么 VS Code 还是要我输账号密码”——问题不在 VS Code，而在仓库的 remote 地址还是 HTTPS。
4. Gitee Pages 实战：仓库托管网页的正确姿势
4.1 Gitee Pages 现状与替代方案
“Gitee Pages 没有了吗”这个问题在社区里出现过很多次，这里说清楚来龙去脉。Gitee Pages 是官方提供的静态网站托管服务，简单说就是你把 HTML、CSS、JS 文件推到仓库，Gitee 自动把它们部署成可以通过公网访问的网站。早期它依赖一个独立的部署机制，后来由于使用量和合规要求，Gitee 对 Pages 的开通方式做了一轮调整，新用户开通时需要通过实名认证并补充一些资料，部分时期甚至暂停新开通。所以“没有了吗”这个说法并不准确，准确的说法是：Pages 服务还在，但开通门槛提高了，并且部署策略上对“代码仓库”与“网页托管”做了更严格的区分。
如果你只是需要一个个人演示网站或者项目展示页，Pages 还是一个廉价可靠的方案。如果你需要更灵活的自定义域名、HTTPS 证书自动更新或者更快的 CDN，那可以考虑先用 Gitee Pages 做基础部署，再配合对象存储或者云服务器做分发，效果更稳定。
4.2 托管静态网站的完整操作
以“把一个 Vue 项目打包后的 dist 目录托管到 Gitee Pages”为例。
第一步，确保仓库里有一个目录叫 dist（或者你网站的根目录），这个目录里放着 index.html。
第二步，进入仓库的“服务”菜单，找到“Gitee Pages”，点击“启动”。部署目录填 dist，强制 HTTPS 这里看你需求，一般建议开启。如果你有自定义域名，可以在“自定义域名”处填，并按要求加一条 CNAME 记录。
第三步，等待一两分钟，Gitee 会生成一个 https://yourname.gitee.io/order-service 这样的访问地址。
我的经验是，平时开发时，可以在本地把 dist 目录加入 .gitignore，只在准备发版时才构建并强制推送：
bash复制npm run build
git add dist -f
git commit -m "build: deploy pages"
git push
这里注意，-f 是为了强制把被忽略的文件加进来，所以一定要确认构建产物里没有密钥或不该公开的配置文件。还有，如果你在仓库里用了 public 这类目录名，注意 Pages 的默认发布分支和发布目录要和你仓库结构对上，不然部署出来 404 或者空白页面，排查起来比较难受。
4.3 分支命名与发布分支的选择
既然提到 Pages，顺便把分支命名规范一起聊掉。很多仓库是单分支走天下，但稍微正规一点的项目，分支管理直接影响交付质量和协作效率。
常见分支命名规则是：
master或main：默认主干分支，代表可发布的稳定版本。develop：开发集成分支，日常功能开发完成后合并到这里。feature/xxx：功能分支，比如feature/user-login。fix/xxx：修复分支，比如fix/order-timeout。release/xxx：发版准备分支，比如release/1.2.0。
Pages 部署时，发布分支一般选 master 或 main，发布目录选站点的根目录或 dist目录。这里有一个坑：如果你部署分支选的是 master，而发版时在 develop 分支直接构建，然后 push 到了 master，Pages 会自动重新部署。如果两次构建内容差异很大，中间会有短暂的版本切换窗口。建议正式项目里，Pages 发布分支单独固定一个分支，例如 gh-pages 或 pages，代码更新流程走正常合并，避免误触发部署。
另外，国内网络环境下，如果你的网页要引用外部 CDN（比如 Google Fonts），用户访问时可能会很慢，甚至卡住整个页面。托管到 Gitee Pages 的站点，建议把资源尽量本地化，或者换用国内可访问的 CDN 地址，实际效果差很多。
5. 开源许可证怎么选：从合规到推广
5.1 常见许可证的核心差异
Gitee 创建仓库时会让选择许可证，很多人直接略过或者选了一个最熟的 MIT，其实这里面的学问不少。许可证决定了别人能用你的代码做什么、要不要开放源码、要不要保留版权声明。
常见许可证的核心差异：
| 许可证 | 商用 | 修改后是否必须开源 | 主要特点 |
|---|---|---|---|
| MIT | 允许 | 否 | 最宽松，只要求保留原版权声明 |
| Apache 2.0 | 允许 | 否 | 宽松，包含明确专利授权条款 |
| GPL v3 | 允许 | 是 | 传染性强，衍生作品必须开源并采用 GPL |
| LGPL v3 | 允许 | 库本身衍生需开源 | 适合库项目，应用层可以闭源 |
| MPL 2.0 | 允许 | 修改文件需开源 | 文件级弱 copyleft，平衡居中 |
如果你开放源代码是希望被广泛使用，哪怕被商业公司集成也不设障碍，MIT 或 Apache 2.0 最合适。Apache 2.0 相比 MIT 多了一个专利保护条款，对大型企业更友好。如果你希望代码的修改版本也必须公开，防止别人白嫖之后闭源不贡献，选 GPL。如果你的项目是给其他人用的库，不想因为用了你的库导致别人整个应用被迫开源，选 LGPL 或 MPL 更稳妥。
5.2 不同项目形态的许可证选择建议
聊完概念，给你一套直接可用的建议：
- 个人项目、工具脚本、示例代码：选 MIT，最简单，知名度高，别人引用时没有心理负担。
- 企业内部标准库、中间件：选 Apache 2.0，兼顾版权保护和专利条款，法务认可度高。
- 需要社区共建的长期开源项目：选 GPL v3 或不带版权的
AGPL v3（注意，AGPL对网络服务也有开源要求，很多云厂商会刻意避开）。如果你希望项目被云厂商集成但同时要求它们开放改动，GPL v3 会是更强约束。 - 只是分享经验、不期望他人构建衍生作品：可以选 “CC BY 4.0”，但要注意，CC 协议一般用于文档、设计资源，不建议用于代码。
一个非常常见的坑是：在 Gitee 创建仓库时选了 MIT，但是仓库里没有放 LICENSE 文件。许可证文件缺失意味着别人无法准确知道你的授权范围，这在法务上是默认“保留所有权利”，和你想表达的开源意愿完全相反。所以在创建仓库时勾选了许可证，一定要确认根目录下确实生成了 LICENSE 文件。
6. 高频问题排查实录
6.1 clone 报错 “git did not exit cleanly（code 128）”
这个报错在 Windows 下特别常见，我至少帮同事排查过十几次。先说结论：这不是 Gitee 独有的问题，而是 Git 客户端在 Windows 上处理远端地址或认证失败时的通用提示。
原因有三类。第一类，远端地址不对。仓库被删了、或者地址里用户名/仓库名拼写有误，都会触发 128。排查方法很简单，去 Gitee 网页端复制地址，重新执行 git remote -v 看当前地址是否正确。第二类，认证失败。如果你使用的是 HTTPS 地址，而账号密码过期或输入错误，也会报 128。处理方式是换成 SSH 地址（见第 3 章），或者在 Windows 凭据管理器里删除旧的 Gitee 凭据，重新推送时再输入正确账号密码。第三类，本地 Git 版本太旧。Windows 上如果用的是系统自带旧版 Git，对某些 TLS 加密算法支持不全，也可能导致连接异常。升级到最新版本即可。
排查这类问题我有个固定思路：先试 git ls-remote git@gitee.com:yourname/order-service.git，这个命令只进行远端通信、不拉完整代码，能快速定位是网络问题还是认证问题。如果这个命令成功，说明 Git 通信正常，问题大概率在本地分支或缓存；如果失败，就要回到远端地址和 SSH key 上找原因。
6.2 创建 Issue 验证码错误
有一位用户遇到“创建 Issue 验证码错误”的问题，新手阶段我也遇到过。原因通常是你处于一个网络环境中间，比如公司防火墙或代理，导致验证码图片加载不完整，或者你输入的验证码和图片不匹配。
处理方法就三步：第一，等验证码图片完全加载出来再填，不用急着输入；第二，如果刷新多次仍然无法识别，清空浏览器缓存或者换一个浏览器内核（Chrome 和 Edge 来回切）；第三，如果是团队协作高频场景，建议直接通过 API 创建 Issue，或者让仓库管理员调整权限设置，允许仓库成员绕过验证码。这类功能限制通常是为了防刷，不影响正常使用。
6.3 非代码资源的分发场景：音源合集、游戏存档与“生存战争”
在热搜词里出现“Gitee 音源合集”“生存战争 Gitee”这些，我一开始也愣了一下，后来发现其实是同一个现象：大家把 Gitee 当成了“免费文件仓库”来用，不只是存代码。
比如有人把软件音源打包成 zip、把单机游戏的存档文件、整合包放在仓库里，通过 Gitee 的下载链接分享给其他人。从平台规范角度看，Gitee 本身是代码托管平台，上传二进制大文件并不是它的设计目标，仓库体积会被限制，大文件下载速度也不如正经的对象存储。但如果你的资源体积不大（比如一个几百 MB 的整合包），用来做临时分发是可行的。操作上建议单独建一个仓库来放这些资源，不要和自己的代码仓库混在一起。原因有二：一是二进制文件随意更改会让仓库体积迅速膨胀，clone 速度会越来越慢；二是大文件混入历史提交之后，如果要清理必须重写历史，代价很高。
另外也要提醒一句：在 Gitee 上分发游戏资源或音源合集时，要确认资源本身没有版权问题，避免因侵权导致仓库被封禁。
7. 实操总结与迁移避坑
7.1 从 GitHub 迁移到 Gitee 的完整路径
很多团队并不是一开始就用 Gitee，而是从 GitHub 转到 Gitee 的。迁移本身不复杂，但有个坑要回避。
最简单的方式是：在 Gitee 新建仓库时选择“导入已有仓库”，填 GitHub 地址，Gitee 会帮你一键导入。如果你需要包含所有分支和标签，建议用命令行镜像方式操作：
bash复制git clone --bare https://github.com/yourname/your-repo.git
cd your-repo.git
git push --mirror git@gitee.com:yourname/your-repo.git
--bare 表示克隆纯 Git 数据，不包含工作区文件；--mirror 表示把远端所有引用（分支、标签）都镜像过去。这套命令执行完，你在 GitHub 上的仓库就完整搬到 Gitee 了。
迁移之后，建议检查这三件事：一是原来的 README 里的徽章、图片地址是否还引用 GitHub，需要改成相对路径或 Gitee 地址；二是 Webhook 配置，Gitee 的 Webhook 地址格式和 GitHub 不同，要在仓库设置里重新配置；三是 CI/CD 工具链的对接，GitHub Actions 无法直接用，得换成 Gitee Go 或者 Jenkens 的 Gitee 插件。
7.2 团队协作中的权限与保护分支设置
最后聊一个比较高级但很实用的话题：保护分支。
Gitee 的仓库设置里提供了“保护分支”的功能。你可以把 master 分支设为保护分支，规则是“不允许直接推送，必须通过 Pull Request 合并”。这对企业级研发来说几乎是标配——它强制了代码评审流程，防止任何一人绕过 review 直接把半成品推到主分支。
配置很简单：在仓库 “管理” -> “分支设置” -> “保护分支” 中，添加 master，勾选“允许合并 Pull Request”并关闭“允许直接推送”。之后团队成员的改动必须新建分支、提交 Pull Request、由管理员或指定 reviewer 审核后合并。
这个功能对数字化转型中的企业特别有用。它是流程规范的技术实现：不靠项目经理每天催“你 review 了吗”，而是平台在操作层面就保证了没人能跳过评审。团队规模越大，这个保护带来的价值越明显。
写在最后
Gitee 对我来说，不是一个简单的代码托管网站，它是把“代码资产管理”和“研发流程规范”落地到一个平台上的基础设施。从创建仓库、推送免密，到 Pages 部署、许可证选择，每一个环节看似琐碎，实际都关系到团队协作效率和项目长期健康。
我个人的建议是：刚开始用 Gitee 时，可以把精力放在“建仓、推代码、配置 SSH 免密”这三件事上；跑顺之后，再去尝试分支规范、保护分支、Pages 托管这些进阶能力。不用一次全部铺开，先解决痛点，再逐步深化。数字化转型不是上一个新系统就完事，而是要靠这些基础工具的每个细节，把团队的协作模式一点一点打磨正规。