paxzone如果你是刚接触代码托管平台，或者已经用过 GitHub 但在国内环境下觉得“差点意思”，那 Gitee 应该是最适合你上手的那个抓手。它被称为“国内版 GitHub”，不光支持 Git 全流程操作，还内置了代码评审、Issue、Pages 静态托管这些实用功能。这篇文章我会直接按实际操作顺序来梳理 Gitee 的使用方法，从环境准备、SSH 免密、仓库创建、日常协作到 Pages 托管，全部走一遍，顺便把大家搜得最多的几个问题（比如上传代码到仓库、clone 报错、许可证选择）一次性讲透。
这篇文章面向的读者很明确：刚接触 Git 的初学者、想把本地项目放到 Gitee 托管的学生开发者、以及想用 Gitee Pages 搭个人站的博主。如果你已经有日常使用 GitHub 的习惯，只是想把部分仓库迁到国内平台，那看 1、2、5 三章基本就够了。
1. 先把手上的环境收拾利索：Git 安装与基础配置
1.1 安装 Git 并验证环境是否可用
在碰 Gitee 网页端之前，第一步永远是先确保你电脑上的 Git 环境是完好的。很多人一上来就注册账号、建仓库，结果到本地推送那一步突然发现 git 命令都没装，来回折腾很费时间。
- Windows：去 Git 官网下载 Git for Windows，安装时一路默认即可。注意安装完成后要新开一个终端窗口，否则 PATH 不会刷新。
- macOS：建议先安装 Homebrew，然后执行
brew install git，这和系统自带的 Git 版本管理不冲突。 - Linux（Debian/Ubuntu）：
sudo apt update && sudo apt install git，CentOS 用yum install git。
装完之后打开终端，输入以下命令验证：
bash复制git --version
如果输出类似 git version 2.39.2 这样的信息，说明环境没问题。这里多说一句：我看到很多教程直接忽略版本检查，但实际踩坑时，老版本 Git 在 Windows 上对换行符和凭据管理器的兼容性差异很大，有条件就尽量装新版本。
1.2 提交者身份配置：这一步不配好，后面全是“无名氏”
Git 每次提交代码，都会自动记录两样东西：提交者名字和提交者邮箱，这两个信息作为 commit 的元数据被永久写入历史记录。如果你不配，Git 会从系统用户名猜一个，提交到 Gitee 后显示出来的提交人完全对不上你的账号，在多人协作时特别容易出问题。
打开终端，执行：
bash复制git config --global user.name "你的名字"
git config --global user.email "你注册Gitee用的邮箱"
这里必须强调的是：邮箱建议和 Gitee 注册邮箱保持一致。虽然 Git 允许随意填写，但 Gitee 的账户关联机制会通过邮箱把提交记录映射到你的账号上。邮箱不一致的后果就是你的 commit 头像和主页贡献图都不更新，这个细节我可以负责任地说，90% 的新手遇到过。
检查配置是否生效：
bash复制git config --global --list
能看到 user.name 和 user.email 就说明配置完成。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. SSH 免密配置：一次配好，后面推送再也不用输入密码
2.1 生成密钥并添加公钥到 Gitee
Gitee 支持和 GitHub 一样的 HTTPS 与 SSH 两种远程访问方式。HTTPS 方式每次 push 都要输用户名密码，就算在 Windows 上勾选了凭据管理器，也偶尔会抽风。SSH 方式通过密钥对认证，配置好以后 push、pull、clone 全程免密，这才是真正的日常体验。
生成 SSH 密钥对，打开终端输入：
bash复制ssh-keygen -t rsa -b 4096 -C "你注册Gitee用的邮箱"
-t 指定算法类型，-b 指定位数，-C 是注释标识，通常填邮箱方便区分。命令执行后会让你确认保存路径和设置 passphrase，保持默认路径直接回车即可。passphrase 可以留空，但如果你的电脑有其他人使用，建议设置一个。
生成的密钥默认在用户目录的 .ssh 文件夹下，公钥文件是 id_rsa.pub，私钥文件是 id_rsa。查看公钥内容：
bash复制cat ~/.ssh/id_rsa.pub
复制从 ssh-rsa 开始的完整内容，然后登录 Gitee，点击右上角头像 -> 设置 -> 安全设置 -> SSH 公钥，标题随意填（比如“我的办公电脑”），把公钥粘贴进“公钥”输入框，点击确定。
关键经验：公钥只给 Gitee，私钥永远不要发给任何人。如果有人拿到了你的私钥，就等于拿到了你仓库的完整读写权限，这个底线一定守住。
2.2 验证免密配置是否生效
公钥添加成功后，回到终端验证：
bash复制ssh -T git@gitee.com
如果是第一次连接，会提示确认主机指纹，输入 yes 回车。随后看到类似下面的输出就代表认证成功：
code复制Hi XXX! You've successfully authenticated, but GITEE.COM does not provide shell access.
看到 successfully authenticated 这个短语就是成功了。到这里，SSH 免密这块就彻底搞定。以后不管你 clone 自己的仓库、还是拉取别人的公开仓库，只要用的是 SSH 地址格式，全程都不需要输密码。
补充一点：如果你之前用 HTTPS 方式 clone 过仓库，想切换到 SSH，不需要重新 clone，进入本地仓库目录后执行：
bash复制git remote set-url origin git@gitee.com:你的用户名/仓库名.git
这招尤其适合已经在本地写了很多代码、不想重新拉下来覆盖的人。
3. 在 Gitee 上创建仓库并完成首次推送
3.1 网页端建仓的每一个参数到底怎么选
进入 Gitee 首页，点击右上角“+”号选择“新建仓库”，会看到一个包含多项参数的创建表单。这些参数里有些直接决定仓库以后的使用方式，我分别讲一下：
- 仓库名称：必填项，只允许字母、数字、下划线、中划线、点。建议全小写、单词之间用短横线连接，比如
my-blog、springboot-demo。这个名称会出现在你的仓库 URL 里，一旦创建后也能改，但会影响已有链接，所以一开始就想好。 - 路径：这也是 URL 的一部分，默认会和仓库名称一致。如果你不想仓库名太长，可以把路径改成短一点的别名。
- 开源许可证：这个很多人随手一选，但其实非常重要。它决定了别人能不能用、怎么用你的代码。具体的选型建议我在 3.2 里专门展开说。
- 初始化仓库：勾选“初始化仓库”后会自动生成 README 文件、
.gitignore文件，并让你选择语言模板。.gitignore` 很重要，它能自动屏蔽编译产物、IDE 配置文件等不需要入库的文件。 - 公开 / 私有：公开仓库任何人都能看到和 clone，私有仓库只有你自己和被你添加的协作者能看到。注意一点：Gitee Pages 服务只支持公开仓库，后面要做网页托管的话这一点要提前规划好。
填完之后点击“创建”按钮，仓库就建好了。此时你会得到一个远程仓库地址，有 HTTPS 和 SSH 两种格式，后面推送代码要用。
3.2 开源许可证怎么选：MIT、Apache-2.0、GPL-3.0 到底区别在哪
“Gitee开源许可证选什么”是我看到提问频率很高的问题。许可证不是随便填的，它从法律层面规定了别人使用你代码的边界。常见的几个选项：
| 许可证 | 核心特点 | 适合场景 |
|---|---|---|
| MIT | 几乎没有限制，允许商用、修改、再分发，只需要保留版权声明 | 个人开源项目、工具类代码，希望最多人使用 |
| Apache-2.0 | 和 MIT 类似，但额外包含专利授权条款，对专利诉讼有保护 | 公司开源项目、涉及专利风险的中间件 |
| GPL-3.0 | 强制“传染”，衍生作品也必须开源且同协议 | 希望代码永远开源库，用于自由软件运动 |
| MPL-2.0 | 文件级开源，修改过的文件需要开源，其他文件不受影响 | 混合闭源和开源的库 |
没有“最好”的许可证，只有“最合适”的许可证。我的建议是：如果你的项目是学习笔记、演示 Demo、工具脚本，直接选 MIT，这是最宽松也最不容易产生纠纷的；如果你是公司团队或打算做一个长期维护的开源中间件，Apache-2.0 更稳妥；如果你的项目本质上就是要拒绝被闭源商用，再考虑 GPL-3.0。
补充：如果建仓库时选了某个许可证，会在仓库根目录自动生成 LICENSE 文件。如果你是先建了仓库、后决定换许可证，直接修改这个文件并重新推送就行，不需要重建仓库。
3.3 本地项目首次推送：完整命令流程
接下来是我们最常见的场景：本地已经有一个项目文件夹，现在要推到刚才建的 Gitee 空仓库里。这个流程看起来简单，但首次推送的细节非常容易出错。
假设你的项目在 ~/my-project 目录下，进入项目根目录：
bash复制cd ~/my-project
git init
git init 会在当前目录下创建一个隐藏的 .git 文件夹，表示这个目录变成了一个 Git 仓库。这一步只做一次，千万不要在嵌套的子目录里重复 init，否则会出现“仓库套仓库”的混乱局面。
然后添加所有文件到暂存区：
bash复制git add .
这个 . 表示把当前目录下的所有未忽略文件都加到暂存区。git add 之后可以通过 git status 检查当前暂存状态，确认是否有不小心加进来的敏感文件（比如 .env 配置文件、密钥文件等）。
紧接着提交第一次版本：
bash复制git commit -m "first commit"
-m 后面是提交说明。第一次提交用 first commit 或 init project 都可以，但从第二次开始，提交说明建议写清楚“做了什么改动”，这样以后回溯历史时才有参考价值。
接下来添加远程仓库地址，注意用 SSH 格式：
bash复制git remote add origin git@gitee.com:你的用户名/仓库名.git
origin 是远程仓库的默认别名，想改成别的名字也可以，但 origin 是社区约定俗成的叫法，没必要特立独行。
最后推送：
bash复制git push -u origin master
-u 参数的作用是把本地 master 分支和远程 origin/master 分支建立关联。建立关联后，以后直接执行 git push，Git 就知道往哪个远程分支推送，不需要再输入完整命令。
注意：有些 Gitee 仓库默认分支名可能是
main而不是master，这取决于你在初始化仓库时选择的设置。建议在推送前先看仓库页面显示的分支名，如果显示master就推master，显示main就推main。强行推名字不匹配的分支会导致本地和远程出现两个并列分支，新手经常被这个问题吓到。
推送成功后，刷新 Gitee 仓库页面，就能看到你本地的所有文件已经在线展示。
3.4 首次推送被拒的几种情况
情况一：远程仓库里有 README 或 LICENSE 文件，本地没有。 因为你在建仓库时勾选了“初始化仓库”，Gitee 自动生成了 README 文件。本地推送时，远程仓库已经有一个 commit 了，而本地是从零开始的，历史上的提交互不相干，就会被拒绝。解决办法有两种：一种是在本地先拉取远程仓库：git pull --rebase origin master，把远程的 README 先合并到本地再推送；另一种是干脆删掉远程的自动生成文件，但这个要谨慎操作。
情况二：没有任何 commit 就推送。 Git 不允许推送一个空仓库上去，必须先至少有一次 commit。
情况三：提交者信息错误。 如果没有配置 user.name 和 user.email，push 时会要求你补齐身份信息，报错信息里会有乱码一样的人名提示。
顺便提一嘴：如果要覆盖远程仓库的文件，不要用 git push -f 强推。强推操作会让远程仓库的历史记录回退，在多人协作项目里这是极不负责任的行为。如果确实需要覆盖，建议先和协作者沟通，用 git revert 或 git reset 处理。
4. 日常开发协作流程：clone、分支、提交、合并
4.1 把 Gitee 上的项目拉取到本地
换了一台电脑，或者同事把一个项目传到 Gitee 之后，你想在本地开始干活，第一步就是 clone（克隆）。打开终端进入你想存放项目的目录，执行：
bash复制git clone git@gitee.com:你的用户名/仓库名.git
clone 命令会同时完成三个动作：在当前目录创建仓库同名文件夹、初始化本地 Git 仓库、把远程默认分支拉取到本地。整个过程不需要手动 git init 和 git remote add，非常方便。
经常有同学问“怎么把 Gitee 上的小程序项目拉到微信开发工具平台”，这个流程其实是一样的：先在本地把项目 clone 下来，然后打开微信开发者工具，选择“导入项目”，目录指向刚才 clone 的文件夹，填入小程序的 AppID 即可。Gitee 并不限制代码的最终用途，它只负责托管，真正跑起来还是靠对应的开发工具。
4.2 分支命名规范：从一开始就定好规则
分支是 Git 里最重要的协作工具。一个仓库可以有多个分支，每个分支就是一条独立的开发线。当你需要开发一个新功能、修复一个 bug，正确的做法不是直接在主分支上改，而是从主分支分出一条新分支，开发完再合并回去。
关于分支命名，Gitee 官方和社区认可度较高的规范是这样的：
- 主分支：
master或main，永远保持稳定可发布的状态 - 开发分支：
develop，日常集成分支 - 功能分支：
feature/功能描述，比如feature/user-login - 修复分支：
fix/问题描述，比如fix/order-price-error - 发布分支：
release/版本号，比如release/v1.0.0
创建并切换到新分支：
bash复制git checkout -b feature/user-login
这条命令等价于先 git branch feature/user-login 再 git checkout feature/user-login，-b 就是“新建并切换”的简写。
分支命名建议全小写、用斜杠分隔类型和描述。不要用你的名字命名分支（比如 zhangsan），因为你走了之后这个分支基本就成僵尸分支了，没人知道这段代码是什么功能。
4.3 日常提交与同步：保持节奏比写多写少更重要
在日常开发中，你反复用到的命令主要是这三个：git add、git commit、git push。但这里有一个非常常见的误区：很多人把 commit 当备份用，写了一上午代码，直到吃饭前才 commit 一次，提交信息写着“大改动”。这种习惯不但让代码评审变得很难，出问题时也无法精准回退。
我的建议是：在一个功能点完成、代码能编译通过的时候，就应该 commit 一次。提交信息用一句话描述这次改动，比如：
bash复制git add src/pages/login.js
git commit -m "完善登录页表单校验逻辑"
工作区里的多个文件可以分多次 add、分多次 commit，不一定非得一次全提交。Git 的暂存区机制设计出来就是为了这种“分块提交”的场景。
另外一个高频问题：在多人协作时，push 之前要不要先 pull？答案是必须要。如果你不改动远程已有的文件，直接 push 没问题；但如果远程分支有新的提交，而你本地没有同步，Git 会拒绝推送并提示 “Your branch is behind 'origin/master'”。这时候先拉取再推送：
bash复制git pull --rebase origin master
git push origin master
--rebase 参数的作用是把你本地的提交“挪”到远程最新提交之后，让提交历史保持一条线，比默认的 merge 方式更整洁。但要注意：rebase 后如果有冲突，需要逐个文件解决冲突。
4.4 提交 Pull Request（PR）并参与代码评审
如果你是在公司团队或开源项目里协作，一般不会直接往主分支推代码，而是通过 Pull Request（Gitee 里叫 Pull Request，简称 PR）流程。
标准流程是这样的：
- 先从主分支拉出功能分支，比如
feature/user-login - 在功能分支上完成开发，多次 commit
- 把功能分支推送到 Gitee：
git push -u origin feature/user-login - 在 Gitee 仓库页面点击“Pull Request”，选择源分支和目标分支
- 填写 PR 标题和描述，说明改了什么、为什么改，并关联对应的 Issue
- 等待仓库管理员或协作者评审，根据意见修改后继续 push 到同一分支，PR 会自动更新
- 评审通过后合并
我第一次参与开源项目提交 PR 时，总想一次把所有问题都修复，结果 PR 变得很大，reviewer 迟迟不合并。后来才明白，一个 PR 只解决一个问题，关联一个 Issue，评审效率和合并概率都会大幅提升。这是所有 Git 平台通用的最佳实践，Gitee 也是一样。
5. 用 Gitee Pages 托管网页：现在还能不能用
5.1 澄清一个热门疑问：Gitee Pages 并没有彻底消失
“Gitee Pages 没有了吗”这个话题在开发者社区里出现过很多次，原因是 Gitee Pages 服务确实经历过一段时间的调整，很多用户的旧链接突然无法访问，给不少人造成“服务下架”的印象。但根据我的实际使用和观察，Gitee Pages 服务仍然可用，只是使用门槛变高了：需要账号完成实名认证、仓库必须是公开的、部署内容需要符合合规要求。如果你的账号没实名，或者仓库是私有的，在部署页面会直接看不到可用的部署选项。
所以，如果你搜到这个标题并担心 Pages 挂了，不建议直接放弃这个方案。先检查自己账号的实名状态，再确认仓库是公开的，重新走一次部署流程，大概率能解决问题。
5.2 部署一个静态站点的完整步骤
假设你有一个静态网站项目，里面只有一个 index.html，要托管到 Gitee Pages，流程如下：
- 把项目推送到 Gitee 仓库，确保仓库是公开的
- 进入仓库页面，点击顶部菜单的“服务” -> “Gitee Pages”
- 如果系统提示实名认证，先去账户设置里完成
- 在部署页面选择要部署的分支（一般是
master或main），部署目录留空就表示仓库根目录 - 点击“启动”按钮，等待系统自动构建
- 部署成功后，你会得到一个形如
https://用户名.gitee.io/仓库名/的访问地址
之后每次更新项目，重新 push 到对应分支后，需要回到 Gitee Pages 管理页面手动点一下“更新”。Gitee Pages 不像某些平台能自动监听代码变化然后触发重建，这一点要注意。
5.3 Pages 部署的一些限制与替代方案
根据官方文档和实际体验，Gitee Pages 目前支持的静态文件类型包括 HTML、CSS、JavaScript、图片等常见的 Web 静态资源。它不支持服务端脚本（比如 PHP、Node.js 后端），这一点从“静态托管”的定位就能理解。
如果项目是使用 Vue、React 这类框架构建出来的静态资源包，部署方式完全一样：本地执行 npm run build 生成 dist 目录，把 dist 目录里的内容推送到仓库，部署目录填 dist 即可。
除了 Gitee Pages，常见的替代静态托管方案还有 Cloudflare Pages、GitHub Pages 和服务器自建 Nginx。如果你需要域名绑定，Gitee Pages 支持自定义域名，在部署详情页里绑定并设置好 CNAME 解析即可。
6. 高频报错与避坑实录
6.1 clone 报错“git did not exit cleanly”怎么办
在 Windows 上使用 Gitee 时，经常有人遇到这样的报错：在 IDEA 或 VS Code 里点 clone 时，弹窗显示 “git did not exit cleanly (exit code 128)”。这个报错的本质不是 Gitee 出了问题，而是本地的 Git 命令行在底层执行 clone 时遇到了错误，IDE 把这个错误转述成了比较让人摸不着头脑的一句话。
排查步骤按顺序走：
- 先用终端命令行手动试 clone：
git clone git@gitee.com:你的用户名/仓库名.git，看到终端里具体的报错信息。这一步能把 IDE 的干扰排除掉，直达问题本质。 - 如果报错是
Permission denied (publickey)，说明 SSH 公钥没配置好，回到第 2 章重新检查。 - 如果报错是
Repository not found，一般就是地址写错或者仓库是私有但你没权限。 - 如果报错是
Failed to connect to gitee.com port 443: Timed out，这是网络问题，稍后重试或检查网络环境。
在 IDE 里 clone 之前，建议先在命令行确认 git 能用、SSH key 已经配置好，再回到 IDE 操作，这样能省下很多排查时间。
6.2 推送代码时报 403 或“没有权限”
推送时如果遇到 remote: 403 Forbidden，最常见的场景有两个。第一种是仓库是别人的，你只是被添加为协作者，但你在本地 remote 配置里用的账号没有对应权限。第二种是在本机存在多个 Git 账号的情况下，SSH 客户端匹配到了错误的密钥，把 A 账号的密钥发给了 B 账号的仓库。
我的排查方法是查看当前远程地址和本地用户：
bash复制git remote -v
git config user.name
git config user.email
如果发现信息不对，可以用 git remote set-url origin 新地址 修改。如果涉及多账号，建议用 SSH config 文件为不同域名指定不同的密钥文件，但这个操作比较复杂，如果不用多账号可以暂时忽略。
6.3 创建 Issue 时提示验证码错误
这个问题的原因很明确：账号没有绑定手机号，或操作频率过高，Gitee 的安全机制会要求输入手机短信验证码来进行身份验证。但很多用户在弹窗里输入的验证码是正确的，却仍然提示错误，这通常是因为浏览器缓存了旧的页面状态。
解决办法按顺序尝试：
- 刷新页面，重新尝试创建 Issue
- 绑定手机号：设置 -> 安全设置 -> 手机绑定
- 清除浏览器缓存或换一个浏览器
- 稍等几分钟再试，防止操作频繁被临时限制
如果急着要用但验证码一直出问题，可以先在 Issue 板块里用已有的模板提交，或者通过仓库的“新建任务”功能绕过验证码，但长期来看绑定手机号才是根本解法。
6.4 换行符、文件大小、提交错文件等杂项问题
把常见问题整理成一张速查表，方便你遇到问题时快速索引：
| 报错或现象 | 原因 | 解决办法 |
|---|---|---|
| warning: LF will be replaced by CRLF | 换行符在 Windows 和 Linux 之间自动转换 | 在仓库根目录添加 .gitattributes 文件，统一配置换行符策略 |
| remote: error: File is XX MB | 上传了超过平台限制的大文件 | 使用 Git LFS 管理大文件，或把大文件移出版本管理 |
| fatal: A branch named 'master' already exists | 分支名和已有分支冲突 | 用 git branch 检查已有分支，换一个分支名 |
误提交了 .env 或密钥文件 |
敏感信息被提交到仓库 | 先从仓库移除文件，再修改密钥，账号密码相关的必须重置 |
| git push 时提示更新被拒绝 | 远程分支比本地新 | git pull --rebase 后重新推送 |
| commit 作者显示不正确 | 邮箱和 Gitee 账号不匹配 | 修改 user.email，并修改历史提交的作者（可用 git rebase 或 filter-branch） |
敏感文件这一点我再多强调一下：很多人把一个含密钥的仓库设为私有，就以为万事大吉，但私有仓库的协作者如果安全意识薄弱，密钥照样可能泄露。正确的做法是无论如何都不把密钥提交到仓库里，本地开发时用环境变量或.gitignore 排除。
写在最后：给刚上手 Gitee 的人一个忠告
我在实际带新人用 Gitee 的过程中，发现大家最容易掉的坑不是命令记不住，而是习惯出了大问题。有人把仓库当网盘用，什么东西都往里塞；有人遇到冲突就慌张，直接用 rm -rf 删掉整个文件夹重新 clone；还有人喜欢在 master 上直接开发，分支工具完全不用。这些做法短期内似乎“更省事”，但一旦项目规模变大、人数变多，账都会加倍还回来。
我的建议很简单：不管你现在是个人项目还是团队协作，从第一天开始就按照标准流程走——用 SSH 免密、建仓库时选好许可证、开发时建独立分支、提交信息写清楚、敏感文件坚决不入库。这些习惯养成之后，Gitee 会变成你手中非常顺手的代码管理工具，而不是一个偶尔让你崩溃的“在线文件夹”。
另外一个小技巧：本地项目根目录里放一个 README.md 文件，把项目的用途、启动方式、目录结构写清楚。你写的时候可能觉得麻烦，但三个月后再回来看这个项目的时候，你会发现这份 README 比任何代码注释都管用。这一点，做过几个项目的人应该都有同感。