1. 为什么每个程序员都该有个“Gitee 储藏室”先说个我自己的惨痛经历。几年前我在本地写博客主题断断续续改了三个月文件夹里最后的版本叫final_v12_真的不改了.zip。结果某天硬盘突然出问题里面所有东西直接报废我花了一个通宵把能找回的碎片拼回来最后还是丢了将近两个星期的代码。从那天起我就养成了一个习惯不管项目大小先建仓库改完就推推送这件事一天都不能拖。Gitee 就是我在国内用得最顺手的代码托管平台。有人拿它跟 GitHub 对比说实话两者核心功能差不多都是承载 Git 仓库的远端服务器但 Gitee 在国内访问速度更快中文界面也更友好注册登录没有那么多门槛企业版和高校版还提供免费的私有仓库。对我这种经常要传几十上百 MB 静态资源、而且大多数时候人在国内的人来说Gitee 的实际体验要比访问 GitHub 顺滑太多。这篇文章不是什么高深的 Git 原理课就是一份我从零开始整理的“保姆级”实操记录注册账号、创建仓库、配置 SSH 密钥、第一次推送、日常提交更新、在 VSCode / PyCharm / IDEA 里推送、还有各种报错的排查方法。只要你能把 Git 装好、能敲命令跟着我这份记录一步步走基本都能在十分钟内完成第一次成功推送。另外我把文章标题里的“储藏室”特别点一下。Gitee 对于程序员来说不只是放代码的地方你完全可以把它当成一个免费的云盘、一个私人笔记库、一个学习资料备份中心。很多不涉及业务机密的项目推上去之后不仅多了一重安全备份还能随时在另一台电脑上克隆下来接着干活这种便利感是真的用上之后就回不去了。2. 推送前的基础准备账号、仓库与 SSH 密钥2.1 注册账号与新建仓库时的关键选项先把账号注册好这一步没什么技术含量手机号加验证码就能搞定但我建议你把用户名和邮箱提前规划好。Git 提交记录里会带上这两项信息后边推送时服务器也会校验你的身份如果邮箱跟注册邮箱对不上推送时经常会被拒绝。注册完成之后登录 Gitee右上角有一个“”号按钮点开选“新建仓库”这里有几个字段需要认真填仓库名称尽量用英文小写加短横线例如my-blog、note-sync避免空格和中文字符。虽然 Gitee 支持中文仓库名但你在命令行里操作时中英文切换很容易出问题别给自己找麻烦。路径这个会拼到仓库地址里创建后还能改但改完远端地址就变了所以最好一次想清楚。开源许可证如果仓库打算公开尽量选一个。最常用的是 MIT别人怎么用都行只要保留版权声明和 Apache-2.0多了专利授权条款大厂项目用得多如果不希望别人拿去商用可以选 GPL-3.0但它有“传染性”你用了 GPL 代码你的项目也得开源。选择 .gitignore 模板这个很实用。比如你选 Python 模板它会自动帮你把__pycache__、.env、venv这类不该上传的文件排除掉。就算创建的时候忘了选后边也能手动补一个.gitignore文件我后面会专门讲。使用 Readme 文件初始化这个仓库新手建议勾选。这样仓库里会有一个说明文件而且你第一次推送时可以直接用git clone克隆下来避免空仓库引起的分支名不匹配问题。这里补充一句如果你创建的是空仓库没有勾选任何初始化文件第一次推送时会遇到一点小坑稍后我在 3.1 节里详细说明。2.2 为什么推荐用 SSH 方式推送以及公钥私钥是怎么回事Gitee 支持 HTTPS 和 SSH 两种推送协议。HTTPS 最简单第一次推送时输入用户名和密码就行但有两个麻烦密码输入次数多了容易被缓存混乱而且我实测 HTTPS 在推送大文件时偶尔会中断。SSH 方式配置好之后Git 客户端和 Gitee 服务器之间会用一对密钥完成身份验证以后推送不需要再输账号密码体验干净利落。密钥是一对的私钥保存在你本机一般是~/.ssh/id_ed25519绝对不能发给任何人公钥可以放在 Gitee 的“安全设置”里告诉服务器“这是我自己”。推送数据时服务器会通过加密机制验证你确实持有对应的私钥验证通过自然就放行了。用个生活化类比公钥就像你家的门锁配好之后谁拿着钥匙都能开私钥就是那把唯一的钥匙只有你手里有。把公钥给 Gitee等于告诉它“这把锁认我手里的钥匙”。2.3 SSH 密钥生成与 Gitee 后台配置的完整流程第一步先确认本机装好了 Git。Windows 上我建议直接去官网下载 Git for Windows安装时一路默认在“Adjusting your PATH environment”这一步选“Git from the command line and also from 3rd-party software”这样后面不管在 CMD、PowerShell 还是编辑器终端里都能直接用 git 命令。第二步打开终端。Windows 推荐用 Git BashmacOS 和 Linux 直接用系统终端就行。执行下面这行命令ssh-keygen -t ed25519 -C 你的Gitee注册邮箱如果不支持 ed25519老系统偶尔会遇到改成ssh-keygen -t rsa -b 4096 -C 你的Gitee注册邮箱执行后终端会问你要把密钥文件保存到哪个位置直接回车使用默认路径即可。接着会要求设置 passphrase这是给你的密钥再加一道保险每次使用时要输入额外的口令。如果你追求无感推送这里直接回车留空就行如果是在多人共用的电脑上操作建议还是设一个。密钥生成后把公钥内容显示出来cat ~/.ssh/id_ed25519.pub复制输出的一整串内容登录 Gitee 后点击头像进入“设置”找到“安全设置”里的“SSH 公钥”标题随便填比如my-laptop公钥栏粘贴刚复制的内容提交保存。验证是否生效在终端执行ssh -T gitgitee.com第一次执行会提示确认主机指纹输入yes回车。如果看到类似Hi 用户名! Youve successfully authenticated, but GITEE.COM does not provide shell access.的输出说明 SSH 配置已经成功了。注意密钥文件默认保存在用户主目录下的.ssh文件夹里id_ed25519是私钥、id_ed25519.pub是公钥。私钥文件千万不要传到网盘、发到聊天工具里一旦泄露别人就能冒充你操作仓库。如果你电脑上之前配置过 GitHub 等其他平台的密钥多密钥管理也简单。默认情况下~/.ssh/id_ed25519只会被 Gitee 使用如果多个平台共用同一个密钥文件也能工作就是把同一把公钥分别填到各个平台上。我用的是更稳妥的方案分别生成id_ed25519_github和id_ed25519_gitee然后在~/.ssh/config里指定哪个域名用哪个密钥。3. 核心实操一条龙完成 Gitee 的代码推送3.1 第一次推送把本地项目送到远端仓库为了讲得清楚我先模拟一个最常见的场景本地有一个叫my-project的文件夹里面已经写了一些代码现在要把它推送到 Gitee 上新建好的空仓库里。首先进入项目目录cd my-project如果目录里还没有 Git 仓库初始化一下git init接下来把项目里的所有文件加入暂存区git add .这里多说一句git add .会将当前目录下所有未被忽略的文件加入暂存。如果你的项目里有密码、密钥、大型数据库文件、依赖包目录等不想上传的内容一定要先配置好.gitignore我后面有专门的说明先不要急着执行这一步。然后提交到本地仓库git commit -m init project提交好了给当前分支命名。不同版本的 Git 初始分支名不一样有的是master有的是main为了让仓库结构跟 Gitee 保持一致手动统一一下git branch -M main接下来把远端仓库地址绑定到本地。这个地址在 Gitee 仓库页面的“克隆/下载”按钮里可以找到选择 SSH 那个选项卡复制。形如git remote add origin gitgitee.com:你的用户名/my-project.git最后推送到远端git push -u origin main-u参数的意思是“记住这个关联关系”以后在仓库里直接敲git push就能推到同一个分支不用再写完整命令。如果一切顺利终端会显示一些统计信息比如main - main然后 Gitee 仓库页面就能看到你的文件了。3.2 日常推送更新的标准操作流程第一次推完之后日常更新就简单多了。也许你刚改完一个 bug或者写完一篇 md 文档想同步到 Giteegit add . git commit -m fix: 修复了页面加载慢的问题 git push三步走非常规律。不过这里有几件事我建议你养成习惯第一提交信息不要写“修改了一些问题”这种口水话。别小看提交信息一个月后你回头看历史能靠提交记录快速定位每次改动的内容。我自己的格式是类型: 简要说明比如feat: 新增登录功能、fix: 处理空指针异常、docs: 更新README。第二推送前习惯性看一眼当前状态git status这个命令会告诉你哪些文件改了、哪些还没加入暂存区、当前在哪个分支。我见过太多人在错误的分支上改了半天代码就是因为没看状态直接开写。第三想查看提交记录用git log --oneline -10简洁版历史记录一眼扫过去就能知道最近十次提交都做了什么。讲到这有人可能会问“我每次改代码都要 add 和 commit太麻烦了吧”实际上真不麻烦习惯之后就是肌肉记忆两秒敲完。而且这种“小步提交、频繁推送”的习惯是最安全的每次改动都能在远端留下备份哪怕本地出了灾难性问题也能轻松回退。3.3 巧妙使用 .gitignore 避免把不该传的文件推上去上一节我提到了.gitignore这是推送前必须搞明白的一个文件。它的作用就是告诉 Git“哪些文件或目录不要纳入版本管理”。举个例子你用 Python 写项目虚拟环境目录venv/动辄几百 MB里面全是本机路径相关的文件推到仓库里既占空间又无意义。还有 IDE 的配置目录如.idea/、.vscode/每个开发者电脑上的配置都不一样也不该强制同步。更严重的是.env文件里可能放着数据库密码、API Key一旦推送到公开仓库等于把秘密直接暴露在网上。一个典型的 Python 项目.gitignore长这样# 依赖包目录 venv/ __pycache__/ *.pyc # 环境变量 .env # IDE 配置 .idea/ .vscode/ *.swp # 操作系统生成文件 .DS_Store Thumbs.db # 构建产物 dist/ build/ *.egg-info/Node.js 项目则要加node_modules/ npm-debug.log* pnpm-lock.yaml用法很简单在项目根目录创建.gitignore文件把规则按行写进去。注意一个原则这个文件本身要提交到仓库里因为它对项目里所有协作者都有效。如果你刚开始没有.gitignore也没关系创建 Gitee 仓库时如果忘了选模板现在补一个文件再推送一次就行。如果已经误提交了某些文件比如.env已经在仓库历史里了光靠.gitignore是拦不住的因为 Git 的追踪记录已经存在。需要用下面的命令把文件从版本控制中移除但保留本地文件git rm --cached .env然后提交并推送一次远端仓库里的.env才会被删除。不过要注意这只能删除当前和未来的副本历史提交里仍然可能留着内容公开仓库的话建议直接改密码或换密钥。3.4 推送标签Tag的细节尤其是 IDEA 里“New Tag”的坑除了常规的代码推送还有一个场景很常用发布版本号。比如你写了一个前端组件库迭代到 v1.0.0 了想打个标签记录下来方便以后随时回看这个版本。命令行里打标签并推送是这样git tag v1.0.0 git push origin v1.0.0如果想把所有标签一次性推送git push --tags删除远端标签的命令是git push origin :refs/tags/v1.0.0但在 IDEA 这类 IDE 里操作时有个地方特别容易踩坑。你用 IDEA 的 “New Tag” 功能创建了标签后记得在 Git 面板里找到“Push Tags”选项或者用 VCS → Git → Push 时勾选“Push Tags”。如果在创建标签时没有勾选推送那标签就只存在于本地远端仓库里完全看不到。我有个朋友每次发布版本后都说“我打了 tag 但别人拉不到”结果一问他根本没推。另外说一句标签和分支不要混淆。分支会跟着提交不断前进标签是锁定在某个具体提交上的静态指针。发布的版本号、里程碑节点适合用标签管理。4. 多环境下的 Gitee 推送实战命令行、VSCode 与 PyCharm4.1 VSCode 里配置 Gitee 推送插件推荐与操作流程我知道很多前端和全栈的朋友几乎整天泡在 VSCode 里命令行虽然强大但能在一个界面里完成所有 Git 操作确实更省心。VSCode 内置了 Git 支持但对初学者来说我建议装两个插件。第一个是Git Graph。它能图形化展示所有分支、提交的关系每一次 commit 之后你点开插件就能看到一条清晰的演进线红色是删除、绿色是新增非常直观。对理解 Git 的工作流特别有帮助。第二个是GitLens。它会在每一行代码旁边标注是谁在什么时候提交的这行改动排查问题时特别有用能够精确定位“这段代码是我上次改的哪一行”。操作流程很简单打开项目文件夹 → 点击左侧源代码管理图标 → 修改文件会自动出现在“更改”列表里。在文件上点加号等同于git add输入提交信息后点对勾等同于git commit再点一下“同步更改”按钮就是推送。第一次用 VSCode 推送时它会弹窗让你输入远端 URL直接把 Gitee 的 SSH 地址粘进去就行。不过要强调的是VSCode 图形化操作方便是方便但它只是帮你把命令包装成了按钮底层执行的还是那些 Git 指令。所以你在图形界面里做完操作一样可以用命令行去验证。4.2 PyCharm 里上传代码到 Gitee从零到推送PyCharm 的 Git 集成做得比 VSCode 更完善毕竟 JetBrains 家的 IDE 在工程管理方面确实细致。打开 PyCharm 后如果项目还没有纳入版本控制菜单栏选择 VCS → Enable Version Control Integration选 Git 即可。把项目文件标记为待提交右键项目根目录或git add对应文件。然后 CtrlKWindows或者 CmdKmacOS打开提交窗口勾选要提交的文件填好提交信息点 Commit。接下来要把代码推送到 Gitee这里有两条路如果还没配置过远端地址菜单栏 Git → GitHub 旁边找不到 Gitee 选项需要在 Git → Manage Remotes 里手动添加URL 填入 Gitee 的 SSH 地址。如果已经配置过直接 CtrlShiftK 打开 Push 窗口点 Push 按钮完成推送。这里有个细节PyCharm 里第一次 Push 会弹出一个链接检查窗口显示“Commits to push”还有被删除文件、新文件等变更汇总。我建议你养成习惯推送前扫一眼这个列表确认没有把不该推送的文件带出去。4.3 多设备同时开发时的推送策略克隆、拉取与冲突处理程序员往往有好几台设备公司一台电脑、家里一台笔记本这时候 Gitee 就真正体现出“储藏室”的价值了。新设备上只需要把仓库克隆下来git clone gitgitee.com:你的用户名/my-project.git克隆下来的项目默认关联了远端仓库直接改、提交、推送跟原来的电脑体验一致。多设备协作时最重要的一个操作是“先拉后推”。在开始写代码之前先执行git pull把远端最新的提交拉到本地。如果在别人已经推了新内容的情况下你直接git push大概率会被拒绝报non-fast-forward错误。遇到这种情况不要慌这其实是 Git 在保护你不覆盖别人的改动。正确的处理方式是git pull --rebase--rebase的意思是把你在本地的新提交“变基”到远端最新提交之后让你的提交像排队一样跟在别人后面。如果两个人恰好改的是同一个文件的同一行就会产生冲突Git 会在文件里用、、标记出冲突区域。你需要手动保留正确的代码删除标记符号然后git add . git rebase --continue完成后正常推送即可。新手上路不建议直接一步到位用 rebase第一次遇到冲突时可以先用默认的git pull让 Git 自动合并如果合并到一半出问题git merge --abort可以安全退回合并前的状态。4.4 批量删库、仓库整理与 Gitee 管理后台的使用技巧做独立开发久了Gitee 上会积攒一堆测试仓库、临时仓库。有的叫test有的叫untitled还有的是复制别人项目学完就扔的。整理仓库时Gitee 没有一键批量删除的功能但进入每个仓库页面后在“管理”标签页的最底部有“删除仓库”按钮。删除前系统会要求输入仓库名来确认这是为了保护你不会手滑删掉重要数据。我建议删除前先用本地git clone把仓库完整拉一份回来确认能正常打开再删。毕竟云端删除没有“回收站”可反悔删了就是真没了。另外如果你有几个项目长期不维护但又有纪念意义不删也行在仓库管理里把“是否开源”设成私有就变成了一个安静的归档柜。想更整齐的话可以创建组织Organization把多个仓库归类到组织名下尤其是当你想把个人项目和团队项目分开管理时这个功能非常有用。5. 推送过程中的常见报错与排查实录5.1 高频错误速查表我把这些年实际遇到过的推送错误整理成了一个表格按出现频率排序报错信息出现原因解决方案Permission denied (publickey)SSH 密钥没配置好或当前用的密钥不对执行ssh -T gitgitee.com检查确认公钥已配置到 Giteeremote: Repository not found仓库地址写错或没有权限访问检查仓库 URL、确认仓库存在、确认你登录的账号是成员failed to push some refs本地和远端提交历史不一致先git pull --rebase再推送或使用git push --force谨慎fatal: not a git repository当前目录没有初始化 Git执行git initfatal: remote origin already exists已经绑定过一个远端地址用git remote -v查看或git remote remove origin重新绑定error: src refspec main does not match any本地还没有任何提交先git add .和git commit再推送Failed to connect to gitee.com port 443网络不通或代理干扰检查网络如果有代理工具检查系统代理设置LF will be replaced by CRLF换行符风格不一致是警告不是错误无需处理或配置git config core.autocrlf true统一转换5.2 详细排查案例一SSH 密钥能验证却推送失败有一次我在新电脑上配置完 Giteessh -T gitgitee.com已经提示验证成功但推送时依然报Permission denied。排查了好一会儿才发现问题出在 Git 使用的身份文件上。因为这台电脑同时配置了 GitHub 的密钥文件而默认情况下 Git for Windows 的 OpenSSH 会优先去找默认路径的id_ed25519。解决方法有两个要么把 Gitee 的公钥也填到 GitHub 对应的密钥文件里要么在~/.ssh/config里明确指定主机和密钥文件。我采用的是后者在配置文件里写Host gitee.com HostName gitee.com User git IdentityFile ~/.ssh/id_ed25519_gitee这样 SSH 连接 Gitee 时就会使用指定的私钥。这个 config 文件对 GitHub 等平台也可以同样处理不同平台互不干扰。5.3 详细排查案例二本地有代码但推送时提示非 fast-forward这种错误通常发生在空仓库初始化之后。如果你在 Gitee 网页端勾选了“使用 Readme 初始化”那远端会多出一个提交而本地是刚git init出来的空项目两端的历史没有共同点直接推送就会被拒绝。解决方案很简单先拉取远端内容再推送。git pull origin main --allow-unrelated-histories git push origin main--allow-unrelated-histories参数的意思是允许两个没有共同提交历史的分支进行合并。合并时如果有文件重名冲突需要手动处理建议尽量选一边保留文件。做完这次合并之后后续推送就不会再出现这种问题了。5.4 推送大文件失败或者仓库体积越来越大的处理建议Gitee 单文件体积和仓库总容量都有一定限制如果项目中不小心提交了一个几百 MB 的压缩包推送过程很可能卡住或者直接报错。如果你的仓库里已经有大型文件不要试图用git add再提交一次来覆盖因为 Git 会把每一次提交都记录在历史里。正确做法是把大文件从项目目录中移走或者从版本控制移除给.gitignore添加规则排除如果大文件还在历史记录里无法剔除需要用git filter-branch或 BFG 这类重写历史的工具清理然后强制推送。这里提醒一句重写历史的操作在对公共仓库做时要极度谨慎因为一旦推送所有协作者都需要重新克隆。如果项目确实需要存放大文件一般建议用网盘、对象存储或单独的静态资源服务来托管仓库里只保留文本引用。这是大多数开源项目都在采用的方案。6. 深入理解推送背后的逻辑分支、远端与提交记录前面讲了这么多操作有人可能想问“我就想传个代码有必要理解这些概念吗”我的回答是理解一点点底层的逻辑能让你遇到问题时不慌。Git 本质上是一个内容寻址的文件系统每次提交都会生成一个唯一的哈希值记录当前时刻项目所有文件的快照。分支就是一个指向提交的指针main分支只是不同时刻指向不同提交的移动光标。你把代码提交commit后main指针就前进了一步推送到远端就是把你本地这些提交同步到 Gitee 服务器上的main指针位置。origin是对远端仓库的默认称呼origin/main就是你本地“记忆”里的远端分支状态。执行git status时显示“你的分支与 origin/main 一致”意思就是本地的提交和远端一模一样。搞清楚这个概念后推送报错就好理解了non-fast-forward错误本质上是本地和远端指向的提交历史出现分叉Git 不允许把历史“倒车”——你本地缺了远端已有的提交它会阻止你直接推。强制推送git push --force的意思是“我确定自己的提交才是正确的把远端的指针强行移动到我的位置”。这个操作会丢掉远端上你没有的提交除非你完全清楚自己在干什么否则不要用。理解了这些很多网上搜到但看不懂的报错帖你就能自己判断问题出在哪一层了。7. 把 Gitee 真正用起来Pages 静态托管与学习笔记场景聊完了推送本身我再说一个经常被忽略的“隐藏功能”——Gitee Pages 静态托管。它相当于一个简化版的静态网站托管服务专门用来托管纯前端项目、个人博客、文档站点。操作流程很简单准备一个包含index.html的仓库推送到 Gitee进入仓库的“服务”菜单找到 Gitee Pages选择部署分支和目录点击启动系统会给你分配一个网址别人就能通过这个网址访问你的页面了。我用这个功能托管过自己的前端学习笔记、简历模板和一些小工具的在线演示。最直接的好处是做完一个纯前端小项目不用买云服务器、不用配 Nginx推上去点一下 Pages 就能给同事发链接看效果这种“从代码到可访问网址”的完整链路比发一个 zip 压缩包专业太多。对于爱写技术笔记的程序员我还有一个建议在 Gitee 上建一个私有仓库专门用来存 Markdown 笔记。笔记的好处是纯文本、体积小推起来飞快而且天然支持版本控制。今天是初稿明天补充一段每次改动都有记录想回退随时可以。因为仓库是私有的你写什么都行不用担心被别人看到。我在这个仓库里存了将近三年的学习笔记累计几百个文件偶尔遇到一个“好像以前记过但忘了放哪”的问题直接在克隆下来的本地目录里全局搜索几秒钟就能定位这种安全感和检索效率是本地文件无法提供的。结合 Gitee Pages这些笔记还能一键生成在线站点相当于拥有了个人维基。一篇笔记推上去改一下仓库路径浏览器里就能以网页形式阅读。我自己就是这么维护“技术收藏夹”的每周抽一点时间整理日积月累不知不觉就沉淀出了几万行的资料库。8. 最后的几点经验与建议推送这件事回头看其实就三步本地提交、关联远端、推上去。难的不在命令而在习惯。Git 学起来像是学骑自行车一开始老是担心摔跤但一旦掌握就成了不需要思考的本能动作。作为过来人我给几条或许能让你少走弯路的建议。第一提交信息写清楚这比代码注释更重要。代码注释解释的是“这段代码怎么工作”提交信息解释的是“为什么要有这次改动”。三个月后甚至三年后你翻着git log看旧提交一条清晰的提交信息能帮你瞬间回忆起当时的决策。第二频繁推送别等“做完了再推”。很多人的习惯是把一个功能全部写完才 commit、才 push这个习惯风险极大。功能开发周期往往比预想的长中途可能遇到改需求、电脑出问题、自己改崩了想回退。所以正确的节奏是每完成一个小步骤就提交一次每个可运行的状态就推送一次。第三私有仓库是你的保险柜公开仓库是你的门面。跟业务无关、或者还处在想法阶段的代码先放私有仓库等成熟了、打磨好了再考虑设为公开一旦公开你的代码风格、提交规范、文档质量都会被外界审视这对养成好的工程习惯是有好处的。第四如果文章里哪一步跟你的实际情况对不上先跑一遍git status、git remote -v和git log这三条命令能告诉你 80% 的答案。命令行报错不要慌把报错信息完整复制出来去搜多数情况下都能找到解决方案。我在整理这篇文章时也踩了不少坑上面写的每个排查案例都来自真实经历希望对你有用。