我把一个本地项目推到 Gitee 上结果 push 报错卡了整整一下午。后来才发现不是代码有问题而是我对 Gitee 整个工作流的理解有漏洞。这个平台到底在你的开发流程里担任什么角色值得用一篇完整的文章讲清楚。Gitee 在国内开发者的日常协作里地位比很多人想象中重要。它不仅是 GitHub 的替代品更承担了国内开源生态、企业内网协作、个人代码托管、甚至静态页面部署等多重角色。对新手来说它可能是你第一次接触“远程仓库”的地方对团队来说它是代码流转和审查的中枢。这篇文章我不打算讲那些官网上写烂了的介绍而是从实操出发把创建仓库、vscode 配置、IDEA 连接、代码上传、拉取覆盖、.git 误删后重绑这些高频场景一个一个拆开讲清楚顺带解释背后的原理和坑点。内容会比较长但每一步都可以直接照着操作。适合刚学 Git 的小白也适合那些用了 Gitee 大半年但一直靠“复制命令”活着的同学。建议收藏遇到问题再回来看。1. 从注册到建仓Gitee 的生态定位与基础实战1.1 为什么说 Gitee 是开发者生态的“引擎”聊 Gitee 之前先想一个问题一个代码托管平台到底在开发流程里承担什么职责答案是四个字——“连接”和“流转”。你把本地的代码推到远端把分支合并到主干把 issue 分给协作者把 Pages 部署上线本质上都是代码在不同空间、不同角色之间流转。Gitee 从 2013 年上线到现在围绕这套流转逻辑把代码托管、项目协作、文档管理、持续集成、静态部署等服务都攒齐了所以它对中国开发者来说不只是一个 Git 服务商而是一个数字化开发的中转站。用我自己的体会来说Gitee 最大的价值在于“本地化”三个字。服务器在国内访问速度快注册门槛低中文界面友好社区氛围也接地气。很多高校课程、企业内部培训、个人学习项目都默认用它来交作业、传代码。尤其对于刚接触 Git 的同学Gitee 的图形化界面比 GitHub 更容易上手能帮你先理解“仓库、分支、提交”这些概念再深入去碰命令行。那这一节我们就从最基础的建仓库开始。仓库没建对后面所有操作都是白搭。1.2 创建仓库时的关键决策仓库名、可见性与许可证登录 Gitee 之后右上角点那个“”号选择“新建仓库”会进入一个配置页面。这里有几个字段需要认真填写而不是随意敲两下。第一个是仓库名。Gitee 对仓库名有命名规范只能包含字母、数字、下划线、短横线和点而且不能使用中文、空格、特殊符号。这点和 GitHub 一致。我建议你养成就用“项目名-类型-平台”这种结构的习惯比如blog-backend-api、mini-app-admin-web这样后期仓库多了也好找。仓库名也会出现在仓库 URL 里比如https://gitee.com/用户名/仓库名.git所以尽量全小写避免大小写问题。第二个是开源许可证。这个热搜词下面问的人特别多“Gitee 开源许可证选什么”答案是没有绝对正确取决于你想让别人怎么用你的代码。Gitee 创建仓库时提供常见许可证下拉菜单我简单整理一下区别许可证允许商用必须开源必须保留版权声明典型适用场景MIT是否是个人项目、追求最大传播度Apache-2.0是否是偏基础设施型项目附带专利授权GPL-3.0是是是希望衍生代码也保持开源BSD-3-Clause是否是学术界、宽松分发如果你只是学习练手选 MIT 就行最省事如果你在公司里做 SDK 或中间件Apache-2.0 通常是更稳的选择如果目标是打造一个像 Linux 那样“病毒式传染”的开源项目那就 GPL。还有一个细节如果你把仓库设为私有许可证其实不产生法律意义但将来一旦转为公开许可证就会立刻生效所以别乱选。第三个是是否用 README 初始化仓库。我建议新建仓库时勾选“初始化仓库并添加 README”这样远端会直接生成一个 master/main 分支。之后你在本地可以直接 clone或者在空目录里 remote add都能少踩很多“两边都不认识”的坑。1.3 把一个本地文件夹作为仓库提交上去的两种姿势很多人的第一个问题是“我本地已经写好了代码怎么变成 Gitee 上的仓库”这里有两种姿势对应不同场景。第一种先建远端仓库再 clone 下来。操作顺序是在 Gitee 创建仓库时勾选初始化 README复制 HTTPS 或 SSH 地址本地执行git clone 地址然后把本地代码文件复制进这个克隆好的文件夹里最后git add .、git commit -m init、git push。好处是仓库之间的关联关系自动建立不需要手动配置 remote适合新手。第二种本地目录直接关联远端仓库。如果你本地项目已经写了一堆代码不想多复制一遍就用这种方式。进入项目文件夹执行git init然后git remote add origin 远端仓库地址再git pull origin master --allow-unrelated-histories这一步是把远端 README 拉下来并允许两棵无关历史合并然后git add . git commit -m init git push -u origin master。这里需要重点解释--allow-unrelated-histories这个参数。它的意思是“允许两个没有共同祖先提交的历史合并”。本地刚git init的仓库和远端带 README 的仓库彼此完全没有历史交集直接 pull 会报“refusing to merge unrelated histories”新手十有八九会栽在这。加上这个参数之后就能强行把两边拉到同一个时间线上。1.4 “文件夹能复制到另一个文件夹吗”等同于仓库内容的迁移热搜词里有个问题特别有意思“Gitee 文件夹可以复制到另外一个文件夹吗”我理解这里问的是两种情况都得说清楚。第一种是仓库内移动文件或文件夹比如把src/utils挪到src/shared/utils。因为远端仓库本身不存储“移动”这个操作只有 Git 的提交记录里会记录 rename 事件。你可以直接git mv src/utils src/shared/utils然后 commit 和 push。第二种是跨仓库复制比如想从项目 A 把某个文件夹复制到项目 B。最简单稳妥的办法是clone 项目 A 到本地把目标文件夹复制到项目 B 的目录里再在项目 B 里 commit 上传。如果你想保留历史记录就需要用git log --follow和git format-patch这类导出补丁的方式逻辑复杂日常用得少。大部分情况下把文件复制过去、重新提交一次就够了——虽然历史记录丢了但团队协作中真正关心的是“当前代码正确”。2. 本地与远程的桥梁vscode 和 IDEA 里的 Gitee 实战课2.1 连接方式选择HTTPS 还是 SSH这是个策略问题本地要操作 Gitee 仓库第一步不是装插件而是决定用HTTPS还是SSH来连接远端。这两者的使用体验差别很大。HTTPS 方式就是每次执行 push 或 pull 时Git 会要求你输入 Gitee 的用户名和密码或私人令牌。优点是配置起来零门槛只要 Git 环境正常就能用缺点是重复输入密码很烦虽然系统凭据管理器能记住但换了一台电脑或者用了 CI 环境很容易卡在认证上。SSH 方式基于公钥和私钥配对。你在本地生成一对密钥把公钥配置到 Gitee 账户的 SSH 公钥列表里之后所有 Git 操作都通过密钥自动认证不需要输入密码。从效率和安全性的综合角度我强烈建议一键配置 SSH尤其你打算长期跟 Gitee 打交道。生成密钥的命令很简单ssh-keygen -t rsa -b 4096 -C 你的邮箱-t rsa指定用 RSA 算法-b 4096指定密钥长度 4096 位比默认的 2048 位更安全。生成完会在用户目录的.ssh文件夹下产生id_rsa私钥和id_rsa.pub公钥。私钥一定不要泄露公钥可以随便给别人。把公钥内容复制到 Gitee 的“设置 - 安全设置 - SSH 公钥”里保存后本地执行ssh -T gitgitee.com看到“Youve successfully authenticated”的提示就代表配置成功。之后 clone 时用 SSH 格式地址就一路顺畅了。2.2 vscode 配置 Gitee 完整流程从安装到提交vscode 里配置 Gitee核心就三件事装 Git、装插件、配账户。先确认 Git 装好了。在终端里执行git --version如果提示找不到命令就去 Git 官网下载安装包一路默认安装。装好后在 vscode 的“终端”里进入项目目录执行下面的初始化流程git init git add . git commit -m first commit git remote add origin gitgitee.com:用户名/仓库名.git git push -u origin master如果你在 vscode 里看不到源码管理面板多半是因为左侧栏没有打开“源代码管理”图标点一下左侧分支图标就行。提交的流程是在“更改”列表里点击“”暂存文件顶部输入提交信息点“勾号”完成 commit再点“推送”同步到 Gitee。vscode 还有一个 Gitee 官方插件叫“Gitee”安装后在活动栏会出现 Gitee 图标可以直接查看 Issues、Pull Requests、Star 等数据。不过说实话日常写代码阶段插件主要用来浏览仓库状态真正的 push/pull 操作还是靠内置的 Git 面板或者终端更顺手。插件可有可无别被它好看的界面迷惑。2.3 从 Gitee 下载的代码怎么在 IDEA 里运行“Gitee 下载的代码怎么在 IDEA 运行”是另一个高频问题尤其在学校场景里特别常见。很多同学从 Gitee 上下载了 zip 包然后直接双击 .java 文件发现代码一片红、跑不起来。问题出在思路不对。正确操作分三步走。第一步clone 而不是下载 zip。打开 IDEA选择File - New - Project from Version Control粘贴 Gitee 仓库的 HTTPS 或 SSH 地址点击 Clone。这样做的好处是 IDEA 能识别这是一个 Git 仓库之后可以直接 pull/push而不是一个普通的文件夹。第二步让 IDEA 识别项目类型。用 IDEA 打开一个 Maven 项目时要等右下角的进度条把依赖下载完。如果 IDEA 没有把它识别为 Maven 项目右键pom.xml选择Add as Maven Project。同样Gradle 项目要识别build.gradle。这个步骤是“下载的代码运行不了”最常见的原因——IDE 根本不知道这是个什么项目自然不会帮你构建。第三步配置 JDK 和运行入口。File - Project Structure - SDK里选择你本机的 JDK 版本。然后找到带有main方法的类比如XxxApplication.java或Main.java右键运行。以前我遇到过很多次代码明明没问题但因为项目没有标记src为 source rootIDEA 就找不到入口类这个细节也值得排查。2.4 vscode 拉取 Gitee 项目并覆盖本地项目的正确方式有些场景下你想放弃本地修改让本地代码和 Gitee 远端完全一致。这个操作在 vscode 里并不直观很多人在源码管理面板里点“拉取”发现代码跟想象中不一样。原因是普通的git pull是“合并远端到当前分支”它不会删掉你本地已有的文件而是尽量把两边内容合并起来。只有当你的本地修改和远端修改产生冲突时它才会停下来提示。要实现“彻底覆盖”需要三步组合命令git fetch origin git reset --hard origin/master git clean -fd逐条解释一下。git fetch origin是从远端把所有提交记录和代码拉到本地缓存但不会动你当前的工作区所以这一步是安全的。git reset --hard origin/master把当前分支指针硬性回退到远端 master 分支的位置工作区和暂存区的所有内容都被强制改成远端的内容本地未提交的修改全部丢弃。最后git clean -fd是用来删除没有被 Git 跟踪的额外文件和目录比如你本地新建的临时文件。注意这三条命令组合在一起有“毁尸灭迹”的效果。执行之后本地所有未提交的修改都会消失且无法用常规方式找回。执行前请确认自己真的不需要这些代码或者已经备份过了。如果你只想恢复某个特定文件就不要用这么重的手段用git checkout -- 文件名更精准。3. 把日常操作跑顺完整工作流和提交规范3.1 一条命令一条命令拆解标准提交流程现在假设你已经建好了仓库、配置好了 SSH我们从头到尾把一套标准的提交流程走一遍。不要怕命令行命令在 Git 里是最清晰的语言IDE 按钮做的是同一件事但命令你能看见每一步到底发生了什么。完整流程一般是这样的# 1. 进入项目目录初始化仓库 git init # 2. 把当前目录所有文件加入暂存区 git add . # 3. 提交生成一个本地提交节点 git commit -m feat: 初始化项目完成登录功能 # 4. 关联远端仓库 git remote add origin gitgitee.com:用户名/仓库名.git # 5. 推送本地 master 分支到远端并建立上游关联 git push -u origin master这段流程里git add和git commit是最核心的两个动作。add把文件从工作区放进暂存区commit把暂存区内容固化成一次提交。很多新手不理解为什么需要“暂存区”这个概念我用一个生活化类比工作区是你的桌面暂存区是待寄出的信封commit 是你把信投进邮筒。你可以先挑几封信放进去add 指定文件再统一寄出commit这样一次提交就能包含多个相关改动而不是每一次修改都产生一个提交。git push -u origin master里的-u是把本地的 master 分支和远端的 master 分支关联起来。关联之后以后在本地直接敲git push或git pull就够了Git 知道要去哪个远端分支找对应关系不用每次都带参数。3.2 分支管理不该是玄学从创建到合并的完整闭环单干阶段你可以在 master 上直接提交。但一旦有人协作分支管理就是必须掌握的技能。Gitee 和 GitHub 一样支持 Pull RequestGitee 里叫“Pull Request”简称 PR机制流程上先建分支、再提交、最后合并。一个简单但规范的分支模型大概是这样# 创建并切换到 dev 分支 git checkout -b dev # 在 dev 分支上开发正常提交 git add . git commit -m feat: 增加商品列表接口 # 推到远端 dev 分支 git push -u origin dev接下来在 Gitee 网页上仓库界面会提示“有新的推送可以发起 Pull Request”。点进去选择从dev合并到master填写标题和描述就可以发起审查。审查通过后点击“合并”按钮代码正式并入主干分支。这个流程看似多此一举但价值非常大。第一合并到主干之前代码会被同事和 CI 检查一遍问题在源头就被拦住了。第二每个 PR 就是一个完整的工作记录以后回看“这个功能是什么时候、因为什么原因改的”直接搜 PR 就行。第三master 分支永远不会出现“改到一半”的中间态任何时候拉下来都能跑、能发布。3.3 提交信息怎么写才不像灾难现场我这个习惯建议你早点养成每次 commit 的信息要有结构。别写“update”、“修改”、“1”这些信息过一周你自己都看不懂。推荐用业界比较流行的 Conventional Commits 格式说白了就是两个部分类型 描述。常用类型有feat新功能fix修 bugdocs文档更新style格式调整不影响功能refactor重构test测试相关chore构建、依赖等杂项例子fix: 修复登录接口为空时崩溃的问题、feat: 增加用户积分排行功能。这不仅仅是格式好看更重要的是很多自动化工具可以解析提交信息自动生成 changelog、自动决定版本号。你在 Gitee 上看到一个项目历史非常规整那不是作者有强迫症而是有章法地写提交信息带来的结果。3.4 到底提交到 Gitee 还是 GitHub用 git remote 一句话搞定有个热搜问题特别有趣“我用 git 初始化的文件是提交到 github 还是 gitee”这个问题看起来有点好笑但恰恰点出了一个核心概念Git 本身是中立的它不属于任何平台。你用什么远端地址代码就推到哪。判断方式很简单git remote -v执行之后如果输出https://github.com/xxx/xxx.git那就是 GitHub如果输出gitgitee.com:xxx/xxx.git那就是 Gitee如果什么都没输出说明这个仓库还没有关联任何远端你可以通过git remote add origin 新地址来指定。甚至一个本地仓库可以同时关联两个远端git remote add gitee gitgitee.com:用户名/仓库名.git git remote add github gitgithub.com:用户名/仓库名.git git push gitee master git push github master这在“既想国内访问快又想在国际社区曝光”的场景下非常实用。你甚至可以加一个 Gitee 的远端之后不单独记忆直接用git push origin master只要origin指向的是 Gitee 就行。4. 事故自救与排查技巧从 .git 误删到 pages 失效的现场实录4.1 .git 文件删除了怎么重新绑定到 Gitee 已有项目你有没有干过这样的事在文件管理器里看到.git文件夹觉得碍眼甚至觉得占地方就删了结果推不了代码本地好好的 git 仓库突然“失忆”了。这问题我见过太多人问了也是热搜词里最高频的坑之一。先明确.git文件夹就是整个 Git 仓库的“大脑”。它保存了所有提交记录、分支指针、远端配置等元数据。删掉它你的代码文件还在但 Git 不再认识这个目录是一个仓库。重新绑定的操作不复杂按下面步骤走# 1. 重新初始化仓库 git init # 2. 重新关联远端 git remote add origin gitgitee.com:用户名/仓库名.git # 3. 切换到 master 分支有时叫 main git branch -M master # 4. 拉取远端内容并合并 git pull origin master --allow-unrelated-histories # 5. 把当前所有文件提交一次 git add . git commit -m 重新初始化并同步远端 # 6. 推送 git push -u origin master这里的关键是第 4 步那个--allow-unrelated-histories。因为本地是刚 init 出来的空历史仓库而远端已经有提交记录了两者没有任何血缘关系不加这个参数 Git 会拒绝合并。执行完这段之后本地代码就同步到了远端仓库。不过要提醒一下这种方式会把远端的那次历史和新的一次历史“融合”在一个提交里之前的提交记录还在但本地失去了它们。如果你很在意历史记录删 .git 之前应该用git bundle create project.bundle --all打包一份完整备份这是后话。4.2 Gitee Pages 没有了吗聊聊现状和正确开通姿势“Gitee Pages 没有了吗”这个问题在社区里被问了好几年。我的答案非常明确还在一直都有。只是它的入口和审核流程经历了几次调整导致很多人在老教程的路径里找不到入口误以为被下线了。现在的正确路径是登录 Gitee进入一个仓库点击仓库顶部的“服务”菜单在下拉列表里找到“Gitee Pages”进入 Pages 管理页面。在这里你需要选择部署的分支和目录。默认是项目的master分支、根目录。如果你的站点文件在docs文件夹下把目录改成/docs再保存即可。部署的时候要注意几个点。第一实名认证是硬性要求。早期没有这个限制后来为了符合规范使用 Pages 服务需要先完成 Gitee 账户实名认证。没认证的话页面会一直提示你没有权限。这是最多的“Pages 打不开”的原因没有之一。第二仓库必须有 index.html。Pages 服务本质是把你仓库里的静态文件部署到一个公网可访问的地址入口文件必须叫index.html。如果没有它部署会显示成功但访问时会返回 404。第三部署不是即时的。点击“更新”后通常需要等几十秒到几分钟服务才会把最新内容同步到 CDN。别刚点了就疯狂刷新等个两分钟再访问。至于“Pages 没有了吗”的另一个变体——Gitee Pages Pro那是更高一档的服务支持自定义域名、HTTPS 自动续期等适合正式项目。个人学习博客用免费版足够。4.3 本地项目不小心把 .git 删了还有其他补救方案吗上一节我讲了重新初始化绑定远端仓库的办法但如果你不只是删了.git还担心代码本身有丢失风险那我要多啰嗦两句。Git 的“后悔药”并没有想象中那么少。如果你删掉.git之后执行过git init但还没有进行任何提交那之前的 Git 对象可能还有一部分残留在.git文件夹里——不过现在已经被新的.git覆盖了基本没辙。更靠谱的补救策略是养成定期推送的习惯。只要你的代码曾经成功推送到 Gitee 远端那么远端就有备份。删了 .git 最多是本地历史丢了代码本身还在远端重新 clone 一份就能恢复。还有一个小技巧在文件管理器里看不到.git文件夹不等于它不存在很多危险操作都是因为“看不见就以为没有”。在 Windows 里开启“显示隐藏文件”或者在 Mac/Linux 终端里用ls -a就能看到它了。做 git 操作之前建议永远不要手动去动这个文件夹这是底线。4.4 高频问题速查clone 失败、push 被拒、权限异常我在踩过无数坑之后整理了一份 Gitee 日常问题速查表很多问题看一眼答案就能解决现象最常见原因解决思路clone 远程仓库失败网络不稳定或地址复制错误先确认 URL 是否有大小写错误HTTPS 地址换 SSH 地址再试push 提示 403 / 权限不足没有该仓库的写权限或 SSH 公钥没配置检查是不是仓库成员在 Gitee 设置里确认 SSH 公钥已添加push 提示 non-fast-forward远端有本地没有的提交先git pull --rebase拉取并重新应用本地提交再 pushpull 报 unrelated histories本地和远端没有共同祖先使用git pull origin master --allow-unrelated-histories提交时中文显示乱码终端编码问题Windows 下在 Git Bash 里执行git config --global core.quotepath falseclone 时仓库特别大、卡死仓库里有大文件使用git clone --depth 1 仓库地址只克隆最新一次提交网页版上传文件后本地 pull 没反应分支不同步先git fetch然后git pull origin 分支名上传图片或压缩包失败仓库文件大小限制转用 Git LFS 或把文件放到对象存储服务本地修改被覆盖且无法找回reset --hard 误用平时养成 commit 后再操作的意识恢复用git reflog仓库换成另一个账号后 push 失败remote 地址还指向旧账号更新远程地址git remote set-url origin 新地址有两点值得展开讲。git pull --rebase和普通git pull的区别简单说就是普通 pull 会多出一个“合并提交”把两条历史线搅在一起--rebase是把本地的提交挪到远端最新提交的后面历史是一条直线更干净。多人开发时我更喜欢用git pull --rebase这样 git log 看着不混乱。另一个是git clone --depth 1。当你只需要看代码、不关心历史的时候浅克隆能省大量时间。很多仓库有几百甚至几千个提交包含了大量中间版本的大文件全量克隆很慢。浅克隆只拉最近一次提交速度飞快。缺点是后续 pull 可能会有点麻烦因为缺少历史基础不太适合长期协作。4.5 复盘一个稳定的 Gitee 协作习惯应该长什么样文章写到这里我把踩过的坑、常用的命令、关键的选择都拆开讲了。最后分享几个我自己的习惯不算什么真理但确实帮我省了好多次救火的时间。第一新项目起步时花两分钟写好 README 和 .gitignore。README 描述项目用途.gitignore 把node_modules、target、.idea、__pycache__这些产物目录排除掉避免把一堆几百 MB 的依赖推上远端。没有 .gitignore 的仓库用一段时间就会变得又大又乱。第二每天下班前推送一次代码。即使今天改的东西还不完整也先 commit 再 push可以推到自己的分支上。Git 的设计本来就是为了让你随时保存进度烂代码堆在本地和放在远端分支是没有区别的——反正没合并前不会污染主干。第三重要操作前先确认远端状态。执行git reset --hard、git clean -fd、git push --force这类“破坏性命令”之前先敲一下git status看工作区干不干净再翻一下远端最新提交确认你确实想覆盖它。多花十秒钟可以避免毁掉一天的工作量。第四善用 Gitee 的 Issues 和 PR 功能。就算你是一个人开发也可以把 TODO 写成 issue把改动拆分到多个 PR 里。这件事的意义不只是“显得专业”而是让未来的你通过历史记录能快速理解当时为什么要这么做。我在实际使用过程中越来越觉得Gitee 对中国开发者生态来说确实担得起“引擎”这个说法。它把代码托管、协作、文档、部署这些环节串在了一起而用好这架引擎的关键并不是记住多少命令而是把一套清晰的流程变成肌肉记忆。从创建仓库开始到 clone、push、pull、分支合并再到信心满满地点下部署按钮整个过程跑顺了你的开发效率会有一个肉眼可见的提升。如果你正准备把下一个项目放到 Gitee 上希望这篇文章能帮你少走一点弯路。
Gitee实战指南：从创建仓库到代码协作全流程解析
我把一个本地项目推到 Gitee 上结果 push 报错卡了整整一下午。后来才发现不是代码有问题而是我对 Gitee 整个工作流的理解有漏洞。这个平台到底在你的开发流程里担任什么角色值得用一篇完整的文章讲清楚。Gitee 在国内开发者的日常协作里地位比很多人想象中重要。它不仅是 GitHub 的替代品更承担了国内开源生态、企业内网协作、个人代码托管、甚至静态页面部署等多重角色。对新手来说它可能是你第一次接触“远程仓库”的地方对团队来说它是代码流转和审查的中枢。这篇文章我不打算讲那些官网上写烂了的介绍而是从实操出发把创建仓库、vscode 配置、IDEA 连接、代码上传、拉取覆盖、.git 误删后重绑这些高频场景一个一个拆开讲清楚顺带解释背后的原理和坑点。内容会比较长但每一步都可以直接照着操作。适合刚学 Git 的小白也适合那些用了 Gitee 大半年但一直靠“复制命令”活着的同学。建议收藏遇到问题再回来看。1. 从注册到建仓Gitee 的生态定位与基础实战1.1 为什么说 Gitee 是开发者生态的“引擎”聊 Gitee 之前先想一个问题一个代码托管平台到底在开发流程里承担什么职责答案是四个字——“连接”和“流转”。你把本地的代码推到远端把分支合并到主干把 issue 分给协作者把 Pages 部署上线本质上都是代码在不同空间、不同角色之间流转。Gitee 从 2013 年上线到现在围绕这套流转逻辑把代码托管、项目协作、文档管理、持续集成、静态部署等服务都攒齐了所以它对中国开发者来说不只是一个 Git 服务商而是一个数字化开发的中转站。用我自己的体会来说Gitee 最大的价值在于“本地化”三个字。服务器在国内访问速度快注册门槛低中文界面友好社区氛围也接地气。很多高校课程、企业内部培训、个人学习项目都默认用它来交作业、传代码。尤其对于刚接触 Git 的同学Gitee 的图形化界面比 GitHub 更容易上手能帮你先理解“仓库、分支、提交”这些概念再深入去碰命令行。那这一节我们就从最基础的建仓库开始。仓库没建对后面所有操作都是白搭。1.2 创建仓库时的关键决策仓库名、可见性与许可证登录 Gitee 之后右上角点那个“”号选择“新建仓库”会进入一个配置页面。这里有几个字段需要认真填写而不是随意敲两下。第一个是仓库名。Gitee 对仓库名有命名规范只能包含字母、数字、下划线、短横线和点而且不能使用中文、空格、特殊符号。这点和 GitHub 一致。我建议你养成就用“项目名-类型-平台”这种结构的习惯比如blog-backend-api、mini-app-admin-web这样后期仓库多了也好找。仓库名也会出现在仓库 URL 里比如https://gitee.com/用户名/仓库名.git所以尽量全小写避免大小写问题。第二个是开源许可证。这个热搜词下面问的人特别多“Gitee 开源许可证选什么”答案是没有绝对正确取决于你想让别人怎么用你的代码。Gitee 创建仓库时提供常见许可证下拉菜单我简单整理一下区别许可证允许商用必须开源必须保留版权声明典型适用场景MIT是否是个人项目、追求最大传播度Apache-2.0是否是偏基础设施型项目附带专利授权GPL-3.0是是是希望衍生代码也保持开源BSD-3-Clause是否是学术界、宽松分发如果你只是学习练手选 MIT 就行最省事如果你在公司里做 SDK 或中间件Apache-2.0 通常是更稳的选择如果目标是打造一个像 Linux 那样“病毒式传染”的开源项目那就 GPL。还有一个细节如果你把仓库设为私有许可证其实不产生法律意义但将来一旦转为公开许可证就会立刻生效所以别乱选。第三个是是否用 README 初始化仓库。我建议新建仓库时勾选“初始化仓库并添加 README”这样远端会直接生成一个 master/main 分支。之后你在本地可以直接 clone或者在空目录里 remote add都能少踩很多“两边都不认识”的坑。1.3 把一个本地文件夹作为仓库提交上去的两种姿势很多人的第一个问题是“我本地已经写好了代码怎么变成 Gitee 上的仓库”这里有两种姿势对应不同场景。第一种先建远端仓库再 clone 下来。操作顺序是在 Gitee 创建仓库时勾选初始化 README复制 HTTPS 或 SSH 地址本地执行git clone 地址然后把本地代码文件复制进这个克隆好的文件夹里最后git add .、git commit -m init、git push。好处是仓库之间的关联关系自动建立不需要手动配置 remote适合新手。第二种本地目录直接关联远端仓库。如果你本地项目已经写了一堆代码不想多复制一遍就用这种方式。进入项目文件夹执行git init然后git remote add origin 远端仓库地址再git pull origin master --allow-unrelated-histories这一步是把远端 README 拉下来并允许两棵无关历史合并然后git add . git commit -m init git push -u origin master。这里需要重点解释--allow-unrelated-histories这个参数。它的意思是“允许两个没有共同祖先提交的历史合并”。本地刚git init的仓库和远端带 README 的仓库彼此完全没有历史交集直接 pull 会报“refusing to merge unrelated histories”新手十有八九会栽在这。加上这个参数之后就能强行把两边拉到同一个时间线上。1.4 “文件夹能复制到另一个文件夹吗”等同于仓库内容的迁移热搜词里有个问题特别有意思“Gitee 文件夹可以复制到另外一个文件夹吗”我理解这里问的是两种情况都得说清楚。第一种是仓库内移动文件或文件夹比如把src/utils挪到src/shared/utils。因为远端仓库本身不存储“移动”这个操作只有 Git 的提交记录里会记录 rename 事件。你可以直接git mv src/utils src/shared/utils然后 commit 和 push。第二种是跨仓库复制比如想从项目 A 把某个文件夹复制到项目 B。最简单稳妥的办法是clone 项目 A 到本地把目标文件夹复制到项目 B 的目录里再在项目 B 里 commit 上传。如果你想保留历史记录就需要用git log --follow和git format-patch这类导出补丁的方式逻辑复杂日常用得少。大部分情况下把文件复制过去、重新提交一次就够了——虽然历史记录丢了但团队协作中真正关心的是“当前代码正确”。2. 本地与远程的桥梁vscode 和 IDEA 里的 Gitee 实战课2.1 连接方式选择HTTPS 还是 SSH这是个策略问题本地要操作 Gitee 仓库第一步不是装插件而是决定用HTTPS还是SSH来连接远端。这两者的使用体验差别很大。HTTPS 方式就是每次执行 push 或 pull 时Git 会要求你输入 Gitee 的用户名和密码或私人令牌。优点是配置起来零门槛只要 Git 环境正常就能用缺点是重复输入密码很烦虽然系统凭据管理器能记住但换了一台电脑或者用了 CI 环境很容易卡在认证上。SSH 方式基于公钥和私钥配对。你在本地生成一对密钥把公钥配置到 Gitee 账户的 SSH 公钥列表里之后所有 Git 操作都通过密钥自动认证不需要输入密码。从效率和安全性的综合角度我强烈建议一键配置 SSH尤其你打算长期跟 Gitee 打交道。生成密钥的命令很简单ssh-keygen -t rsa -b 4096 -C 你的邮箱-t rsa指定用 RSA 算法-b 4096指定密钥长度 4096 位比默认的 2048 位更安全。生成完会在用户目录的.ssh文件夹下产生id_rsa私钥和id_rsa.pub公钥。私钥一定不要泄露公钥可以随便给别人。把公钥内容复制到 Gitee 的“设置 - 安全设置 - SSH 公钥”里保存后本地执行ssh -T gitgitee.com看到“Youve successfully authenticated”的提示就代表配置成功。之后 clone 时用 SSH 格式地址就一路顺畅了。2.2 vscode 配置 Gitee 完整流程从安装到提交vscode 里配置 Gitee核心就三件事装 Git、装插件、配账户。先确认 Git 装好了。在终端里执行git --version如果提示找不到命令就去 Git 官网下载安装包一路默认安装。装好后在 vscode 的“终端”里进入项目目录执行下面的初始化流程git init git add . git commit -m first commit git remote add origin gitgitee.com:用户名/仓库名.git git push -u origin master如果你在 vscode 里看不到源码管理面板多半是因为左侧栏没有打开“源代码管理”图标点一下左侧分支图标就行。提交的流程是在“更改”列表里点击“”暂存文件顶部输入提交信息点“勾号”完成 commit再点“推送”同步到 Gitee。vscode 还有一个 Gitee 官方插件叫“Gitee”安装后在活动栏会出现 Gitee 图标可以直接查看 Issues、Pull Requests、Star 等数据。不过说实话日常写代码阶段插件主要用来浏览仓库状态真正的 push/pull 操作还是靠内置的 Git 面板或者终端更顺手。插件可有可无别被它好看的界面迷惑。2.3 从 Gitee 下载的代码怎么在 IDEA 里运行“Gitee 下载的代码怎么在 IDEA 运行”是另一个高频问题尤其在学校场景里特别常见。很多同学从 Gitee 上下载了 zip 包然后直接双击 .java 文件发现代码一片红、跑不起来。问题出在思路不对。正确操作分三步走。第一步clone 而不是下载 zip。打开 IDEA选择File - New - Project from Version Control粘贴 Gitee 仓库的 HTTPS 或 SSH 地址点击 Clone。这样做的好处是 IDEA 能识别这是一个 Git 仓库之后可以直接 pull/push而不是一个普通的文件夹。第二步让 IDEA 识别项目类型。用 IDEA 打开一个 Maven 项目时要等右下角的进度条把依赖下载完。如果 IDEA 没有把它识别为 Maven 项目右键pom.xml选择Add as Maven Project。同样Gradle 项目要识别build.gradle。这个步骤是“下载的代码运行不了”最常见的原因——IDE 根本不知道这是个什么项目自然不会帮你构建。第三步配置 JDK 和运行入口。File - Project Structure - SDK里选择你本机的 JDK 版本。然后找到带有main方法的类比如XxxApplication.java或Main.java右键运行。以前我遇到过很多次代码明明没问题但因为项目没有标记src为 source rootIDEA 就找不到入口类这个细节也值得排查。2.4 vscode 拉取 Gitee 项目并覆盖本地项目的正确方式有些场景下你想放弃本地修改让本地代码和 Gitee 远端完全一致。这个操作在 vscode 里并不直观很多人在源码管理面板里点“拉取”发现代码跟想象中不一样。原因是普通的git pull是“合并远端到当前分支”它不会删掉你本地已有的文件而是尽量把两边内容合并起来。只有当你的本地修改和远端修改产生冲突时它才会停下来提示。要实现“彻底覆盖”需要三步组合命令git fetch origin git reset --hard origin/master git clean -fd逐条解释一下。git fetch origin是从远端把所有提交记录和代码拉到本地缓存但不会动你当前的工作区所以这一步是安全的。git reset --hard origin/master把当前分支指针硬性回退到远端 master 分支的位置工作区和暂存区的所有内容都被强制改成远端的内容本地未提交的修改全部丢弃。最后git clean -fd是用来删除没有被 Git 跟踪的额外文件和目录比如你本地新建的临时文件。注意这三条命令组合在一起有“毁尸灭迹”的效果。执行之后本地所有未提交的修改都会消失且无法用常规方式找回。执行前请确认自己真的不需要这些代码或者已经备份过了。如果你只想恢复某个特定文件就不要用这么重的手段用git checkout -- 文件名更精准。3. 把日常操作跑顺完整工作流和提交规范3.1 一条命令一条命令拆解标准提交流程现在假设你已经建好了仓库、配置好了 SSH我们从头到尾把一套标准的提交流程走一遍。不要怕命令行命令在 Git 里是最清晰的语言IDE 按钮做的是同一件事但命令你能看见每一步到底发生了什么。完整流程一般是这样的# 1. 进入项目目录初始化仓库 git init # 2. 把当前目录所有文件加入暂存区 git add . # 3. 提交生成一个本地提交节点 git commit -m feat: 初始化项目完成登录功能 # 4. 关联远端仓库 git remote add origin gitgitee.com:用户名/仓库名.git # 5. 推送本地 master 分支到远端并建立上游关联 git push -u origin master这段流程里git add和git commit是最核心的两个动作。add把文件从工作区放进暂存区commit把暂存区内容固化成一次提交。很多新手不理解为什么需要“暂存区”这个概念我用一个生活化类比工作区是你的桌面暂存区是待寄出的信封commit 是你把信投进邮筒。你可以先挑几封信放进去add 指定文件再统一寄出commit这样一次提交就能包含多个相关改动而不是每一次修改都产生一个提交。git push -u origin master里的-u是把本地的 master 分支和远端的 master 分支关联起来。关联之后以后在本地直接敲git push或git pull就够了Git 知道要去哪个远端分支找对应关系不用每次都带参数。3.2 分支管理不该是玄学从创建到合并的完整闭环单干阶段你可以在 master 上直接提交。但一旦有人协作分支管理就是必须掌握的技能。Gitee 和 GitHub 一样支持 Pull RequestGitee 里叫“Pull Request”简称 PR机制流程上先建分支、再提交、最后合并。一个简单但规范的分支模型大概是这样# 创建并切换到 dev 分支 git checkout -b dev # 在 dev 分支上开发正常提交 git add . git commit -m feat: 增加商品列表接口 # 推到远端 dev 分支 git push -u origin dev接下来在 Gitee 网页上仓库界面会提示“有新的推送可以发起 Pull Request”。点进去选择从dev合并到master填写标题和描述就可以发起审查。审查通过后点击“合并”按钮代码正式并入主干分支。这个流程看似多此一举但价值非常大。第一合并到主干之前代码会被同事和 CI 检查一遍问题在源头就被拦住了。第二每个 PR 就是一个完整的工作记录以后回看“这个功能是什么时候、因为什么原因改的”直接搜 PR 就行。第三master 分支永远不会出现“改到一半”的中间态任何时候拉下来都能跑、能发布。3.3 提交信息怎么写才不像灾难现场我这个习惯建议你早点养成每次 commit 的信息要有结构。别写“update”、“修改”、“1”这些信息过一周你自己都看不懂。推荐用业界比较流行的 Conventional Commits 格式说白了就是两个部分类型 描述。常用类型有feat新功能fix修 bugdocs文档更新style格式调整不影响功能refactor重构test测试相关chore构建、依赖等杂项例子fix: 修复登录接口为空时崩溃的问题、feat: 增加用户积分排行功能。这不仅仅是格式好看更重要的是很多自动化工具可以解析提交信息自动生成 changelog、自动决定版本号。你在 Gitee 上看到一个项目历史非常规整那不是作者有强迫症而是有章法地写提交信息带来的结果。3.4 到底提交到 Gitee 还是 GitHub用 git remote 一句话搞定有个热搜问题特别有趣“我用 git 初始化的文件是提交到 github 还是 gitee”这个问题看起来有点好笑但恰恰点出了一个核心概念Git 本身是中立的它不属于任何平台。你用什么远端地址代码就推到哪。判断方式很简单git remote -v执行之后如果输出https://github.com/xxx/xxx.git那就是 GitHub如果输出gitgitee.com:xxx/xxx.git那就是 Gitee如果什么都没输出说明这个仓库还没有关联任何远端你可以通过git remote add origin 新地址来指定。甚至一个本地仓库可以同时关联两个远端git remote add gitee gitgitee.com:用户名/仓库名.git git remote add github gitgithub.com:用户名/仓库名.git git push gitee master git push github master这在“既想国内访问快又想在国际社区曝光”的场景下非常实用。你甚至可以加一个 Gitee 的远端之后不单独记忆直接用git push origin master只要origin指向的是 Gitee 就行。4. 事故自救与排查技巧从 .git 误删到 pages 失效的现场实录4.1 .git 文件删除了怎么重新绑定到 Gitee 已有项目你有没有干过这样的事在文件管理器里看到.git文件夹觉得碍眼甚至觉得占地方就删了结果推不了代码本地好好的 git 仓库突然“失忆”了。这问题我见过太多人问了也是热搜词里最高频的坑之一。先明确.git文件夹就是整个 Git 仓库的“大脑”。它保存了所有提交记录、分支指针、远端配置等元数据。删掉它你的代码文件还在但 Git 不再认识这个目录是一个仓库。重新绑定的操作不复杂按下面步骤走# 1. 重新初始化仓库 git init # 2. 重新关联远端 git remote add origin gitgitee.com:用户名/仓库名.git # 3. 切换到 master 分支有时叫 main git branch -M master # 4. 拉取远端内容并合并 git pull origin master --allow-unrelated-histories # 5. 把当前所有文件提交一次 git add . git commit -m 重新初始化并同步远端 # 6. 推送 git push -u origin master这里的关键是第 4 步那个--allow-unrelated-histories。因为本地是刚 init 出来的空历史仓库而远端已经有提交记录了两者没有任何血缘关系不加这个参数 Git 会拒绝合并。执行完这段之后本地代码就同步到了远端仓库。不过要提醒一下这种方式会把远端的那次历史和新的一次历史“融合”在一个提交里之前的提交记录还在但本地失去了它们。如果你很在意历史记录删 .git 之前应该用git bundle create project.bundle --all打包一份完整备份这是后话。4.2 Gitee Pages 没有了吗聊聊现状和正确开通姿势“Gitee Pages 没有了吗”这个问题在社区里被问了好几年。我的答案非常明确还在一直都有。只是它的入口和审核流程经历了几次调整导致很多人在老教程的路径里找不到入口误以为被下线了。现在的正确路径是登录 Gitee进入一个仓库点击仓库顶部的“服务”菜单在下拉列表里找到“Gitee Pages”进入 Pages 管理页面。在这里你需要选择部署的分支和目录。默认是项目的master分支、根目录。如果你的站点文件在docs文件夹下把目录改成/docs再保存即可。部署的时候要注意几个点。第一实名认证是硬性要求。早期没有这个限制后来为了符合规范使用 Pages 服务需要先完成 Gitee 账户实名认证。没认证的话页面会一直提示你没有权限。这是最多的“Pages 打不开”的原因没有之一。第二仓库必须有 index.html。Pages 服务本质是把你仓库里的静态文件部署到一个公网可访问的地址入口文件必须叫index.html。如果没有它部署会显示成功但访问时会返回 404。第三部署不是即时的。点击“更新”后通常需要等几十秒到几分钟服务才会把最新内容同步到 CDN。别刚点了就疯狂刷新等个两分钟再访问。至于“Pages 没有了吗”的另一个变体——Gitee Pages Pro那是更高一档的服务支持自定义域名、HTTPS 自动续期等适合正式项目。个人学习博客用免费版足够。4.3 本地项目不小心把 .git 删了还有其他补救方案吗上一节我讲了重新初始化绑定远端仓库的办法但如果你不只是删了.git还担心代码本身有丢失风险那我要多啰嗦两句。Git 的“后悔药”并没有想象中那么少。如果你删掉.git之后执行过git init但还没有进行任何提交那之前的 Git 对象可能还有一部分残留在.git文件夹里——不过现在已经被新的.git覆盖了基本没辙。更靠谱的补救策略是养成定期推送的习惯。只要你的代码曾经成功推送到 Gitee 远端那么远端就有备份。删了 .git 最多是本地历史丢了代码本身还在远端重新 clone 一份就能恢复。还有一个小技巧在文件管理器里看不到.git文件夹不等于它不存在很多危险操作都是因为“看不见就以为没有”。在 Windows 里开启“显示隐藏文件”或者在 Mac/Linux 终端里用ls -a就能看到它了。做 git 操作之前建议永远不要手动去动这个文件夹这是底线。4.4 高频问题速查clone 失败、push 被拒、权限异常我在踩过无数坑之后整理了一份 Gitee 日常问题速查表很多问题看一眼答案就能解决现象最常见原因解决思路clone 远程仓库失败网络不稳定或地址复制错误先确认 URL 是否有大小写错误HTTPS 地址换 SSH 地址再试push 提示 403 / 权限不足没有该仓库的写权限或 SSH 公钥没配置检查是不是仓库成员在 Gitee 设置里确认 SSH 公钥已添加push 提示 non-fast-forward远端有本地没有的提交先git pull --rebase拉取并重新应用本地提交再 pushpull 报 unrelated histories本地和远端没有共同祖先使用git pull origin master --allow-unrelated-histories提交时中文显示乱码终端编码问题Windows 下在 Git Bash 里执行git config --global core.quotepath falseclone 时仓库特别大、卡死仓库里有大文件使用git clone --depth 1 仓库地址只克隆最新一次提交网页版上传文件后本地 pull 没反应分支不同步先git fetch然后git pull origin 分支名上传图片或压缩包失败仓库文件大小限制转用 Git LFS 或把文件放到对象存储服务本地修改被覆盖且无法找回reset --hard 误用平时养成 commit 后再操作的意识恢复用git reflog仓库换成另一个账号后 push 失败remote 地址还指向旧账号更新远程地址git remote set-url origin 新地址有两点值得展开讲。git pull --rebase和普通git pull的区别简单说就是普通 pull 会多出一个“合并提交”把两条历史线搅在一起--rebase是把本地的提交挪到远端最新提交的后面历史是一条直线更干净。多人开发时我更喜欢用git pull --rebase这样 git log 看着不混乱。另一个是git clone --depth 1。当你只需要看代码、不关心历史的时候浅克隆能省大量时间。很多仓库有几百甚至几千个提交包含了大量中间版本的大文件全量克隆很慢。浅克隆只拉最近一次提交速度飞快。缺点是后续 pull 可能会有点麻烦因为缺少历史基础不太适合长期协作。4.5 复盘一个稳定的 Gitee 协作习惯应该长什么样文章写到这里我把踩过的坑、常用的命令、关键的选择都拆开讲了。最后分享几个我自己的习惯不算什么真理但确实帮我省了好多次救火的时间。第一新项目起步时花两分钟写好 README 和 .gitignore。README 描述项目用途.gitignore 把node_modules、target、.idea、__pycache__这些产物目录排除掉避免把一堆几百 MB 的依赖推上远端。没有 .gitignore 的仓库用一段时间就会变得又大又乱。第二每天下班前推送一次代码。即使今天改的东西还不完整也先 commit 再 push可以推到自己的分支上。Git 的设计本来就是为了让你随时保存进度烂代码堆在本地和放在远端分支是没有区别的——反正没合并前不会污染主干。第三重要操作前先确认远端状态。执行git reset --hard、git clean -fd、git push --force这类“破坏性命令”之前先敲一下git status看工作区干不干净再翻一下远端最新提交确认你确实想覆盖它。多花十秒钟可以避免毁掉一天的工作量。第四善用 Gitee 的 Issues 和 PR 功能。就算你是一个人开发也可以把 TODO 写成 issue把改动拆分到多个 PR 里。这件事的意义不只是“显得专业”而是让未来的你通过历史记录能快速理解当时为什么要这么做。我在实际使用过程中越来越觉得Gitee 对中国开发者生态来说确实担得起“引擎”这个说法。它把代码托管、协作、文档、部署这些环节串在了一起而用好这架引擎的关键并不是记住多少命令而是把一套清晰的流程变成肌肉记忆。从创建仓库开始到 clone、push、pull、分支合并再到信心满满地点下部署按钮整个过程跑顺了你的开发效率会有一个肉眼可见的提升。如果你正准备把下一个项目放到 Gitee 上希望这篇文章能帮你少走一点弯路。
