年前有个朋友从 Windows 桌面端切到 Linux 环境干活第一天就差点把键盘拍碎——他在 Gitee 上建好了仓库本地也写好代码了结果对着那个黑底白字的终端窗口发了好一会儿呆完全不知道该敲什么。后来他问我Gitee 在 Linux 下到底怎么用我直接说你以前在图形界面里点点点完成的那些事本质上就是三样告诉 Git 你是谁、把本地代码推上去、把远程代码拉下来。这三件事在 Linux 下用几条命令就能搞定难的是你中途会遇到一堆莫名其妙的报错比如 “refusing to merge unrelated histories” 这种英文长句子一看就头大。这篇文章我就把这几年在 Linux 下折腾 Gitee 的完整流程、踩过的坑、排查过的报错一次讲清楚。适合刚接触 Linux 的学生、第一次把项目交给 Git 托管平台的开发者以及从 Windows 图形界面迁到 Linux 命令行的朋友。你不用记住所有命令按着文章顺序走一遍就能把本地代码和 Gitee 仓库理顺。1. 环境准备把 Git 和 SSH 先搞定1.1 安装 Git 并初始化身份Linux 下使用 Gitee 的第一步不是注册账号也不是打开浏览器而是先在终端里装好 Git。大部分发行版都默认带了这个工具但如果你用的是精简安装或者 Docker 容器很可能没有。可以先敲一下git --version试试。如果提示找不到命令就按发行版选择安装方式# Debian / Ubuntu 系 sudo apt update sudo apt install git -y # CentOS / RHEL / Fedora 系 sudo dnf install git -y安装完成之后不要急着去关联远程仓库先把你的身份信息配置好。这个身份信息会写进每一次提交记录里Gitee 的提交历史页面显示的作者名和邮箱就来自这里。git config --global user.name 你的昵称 git config --global user.email 你注册Gitee用的邮箱这里有个很容易被忽略的点邮箱最好和 Gitee 账号绑定的邮箱保持一致。我见过一些人代码传上去了但提交记录里显示的是一个奇怪的邮箱点进去根本关联不到账号。用git config --global --list可以随时检查当前配置。验证安装是否成功、配置是否生效可以这样看git --version git config --global user.name git config --global user.email确保两行命令都输出正确内容第一步就算完成了。配置好身份这一步没了后面 commit 时要么报错要么记录里出现“未知用户”很尴尬。1.2 生成 SSH 密钥并绑定到 Gitee本地仓库要和 Gitee 远程仓库通信有两种常见协议HTTPS 和 SSH。HTTPS 地址需要每次 push 时输入用户名密码而 SSH 地址是免密的靠的是密钥对。Linux 下开发我是强烈建议用 SSH理由后面详细说。先检查你的用户目录下有没有现成的密钥ls -la ~/.ssh/如果看到id_ed25519和id_ed25519.pub这样的文件说明之前生成过可以直接跳到复制公钥那一步。如果没有就执行ssh-keygen -t ed25519 -C 你注册Gitee用的邮箱后面会提示你设置保存路径和密码短语。路径直接回车用默认值密码短语可以留空也可以设置一个——设置之后每次用私钥会更安全但麻烦一点。我个人的习惯是开发机上不设密码短语方便但前提是电脑本身要做好安全防护。生成之后查看公钥内容并复制cat ~/.ssh/id_ed25519.pub屏幕上会输出一串以ssh-ed25519开头的长字符串这就是你的公钥。把它整段复制然后登录 Gitee 网页端找到“设置” - “SSH公钥”粘贴保存。绑定之后在终端里测量连通性ssh -T gitgitee.com第一次连接会询问是否确认主机指纹输入yes回车。如果看到Hi 你的昵称! Youve successfully authenticated, but GITEE.COM does not provide shell access.这样的提示说明密钥已经生效可以正常通信了。1.3 为什么优先用 SSH 地址而不是 HTTPS 地址很多新手在 Gitee 仓库页面复制地址的时候图省事直接拿了 HTTPS 地址后面每次 push 都要输一次账号密码被折腾得没脾气。其实 SSH 地址和 HTTPS 地址长得很像区别只是前缀协议地址格式示例认证方式使用体验HTTPShttps://gitee.com/用户名/仓库名.git每次需要输入用户名密码重复输入密码容易碰上凭据过期SSHgitgitee.com:用户名/仓库名.git密钥自动认证免密配置一次之后随手用SSH 还有一个优势它基于密钥对私钥留在你自己的机器上公钥给 Gitee别人即使听到你传数据也拿不到有效信息。而 HTTPS 每次传输的是账号密码如果输入时稍微马虎还有可能泄露。对经常在服务器上拉代码、推送代码的人来说SSH 是省心又安全的选择。SSH 用到了 22 端口OpenSSH 默认个别网络的防火墙限制非 80/443 端口这时候可能连不上解决办法有但细节属于网络管理范畴这里不展开。一般我们自己家里、公司、实验室的网络都没问题遇到连不上的情况优先检查密钥和地址端口问题放到最后考虑。2. 让本地仓库和 Gitee 仓库建立连接2.1 最常见场景本地已有项目推送到新建的 Gitee 仓库在 Linux 下使用 Gitee最典型的场景就是你有一个写了几天的项目现在想交给 Gitee 托管保留版本历史。先在 Gitee 网页端新建一个仓库。填好仓库名称、简介其它选项建议这样选初始化仓库不要勾选“使用Readme文件初始化这个仓库”选择分支模型可以选单分支模型master/main团队协作多也可以选多分支模型.gitignore 模板如果网页端提供了模板可以选但后面本地一定要再检查一遍注意别勾选“初始化仓库”这个选项原因我在 2.3 节专门讲那是一个高频坑。网页建好之后拿到 SSH 地址通常长这样gitgitee.com:你的用户名/仓库名.git。然后在本地项目目录里执行以下操作cd /path/to/your/project # 初始化本地 Git 仓库 git init # 查看当前仓库状态 git status # 把所有文件加入暂存区 git add . # 创建第一次提交 git commit -m init project # 关联远程仓库origin 是远程仓库的默认别名 git remote add origin gitgitee.com:你的用户名/仓库名.git # 推送本地 main 分支到远程-u 记录上游分支以后直接 git push 即可 git push -u origin main这里有一个需要特别留意的点git init之后你当前的分支名是什么。新版 Git 默认分支名是main旧版本默认是master而 Gitee 新建仓库时默认分支可能也是master或你选定的其它名字。如果两边分支名不一致git push -u origin main可能会报错提示远端不存在这个分支。最稳妥的办法是先用git branch查看当前分支名再用git branch -M main强制把本地分支重命名为main保持和 Gitee 默认分支一致。这一步多敲一下后面省心得多。第一次推送成功之后刷新 Gitee 网页就能看到代码了。2.2 远程已有仓库直接 clone 更省事如果你不是要把本地项目推上去而是要在一台新机器上把 Gitee 上已有的项目拉下来开发那就用 clone 命令一步到位。git clone gitgitee.com:你的用户名/仓库名.git默认会在当前目录下创建以仓库名命名的文件夹并且自动完成远程分支的跟踪设置。clone 和手动 init remote add 的区别在于clone 帮你在本地建立了完整的工作区、分支跟踪信息和远端配置你不需要再做任何初始化操作进去就能git status看状态。这里有个实用小技巧如果只需要某个分支的代码可以用-b参数指定分支名git clone -b dev gitgitee.com:你的用户名/仓库名.git这样拉下来的本地仓库直接处在dev分支上省得 clone 之后还要切换。clone 的时候如果报权限错误或者地址错误绝大多数情况是 SSH 公钥没配对或者仓库地址复制错了往这两个方向排查基本没错。2.3 网页初始化过仓库导致 push 被拒unrelated histories 问题这个坑太经典了我得单独开一节讲。很多人喜欢在 Gitee 网页新建仓库的时候顺手勾选“使用Readme文件初始化这个仓库”于是远程仓库里就多了一个 README.md 文件和一次提交记录。这时候本地项目也已经有了提交记录两个仓库各自独立、互无关联git push -u origin main就会报错! [rejected] main - main (fetch first) error: failed to push some refs to gitgitee.com:你的用户名/仓库名.git hint: Updates were rejected because the remote contains work that you do not hint: have locally. This is usually caused by another repository pushing to hint: the same ref. You may want to first integrate the remote changes hint: (e.g., git pull ...) before pushing again.这时如果你按提示直接执行git pull origin main还会碰到另一个经典报错fatal: refusing to merge unrelated histories原因很好理解本地仓库的初始提交和远程仓库的 README 提交没有共同的祖先提交Git 认为它们是两条完全不相关的历史线默认不敢自动合并。解决办法有两个我更推荐第一个方法一先在网页端把远程仓库清空或删掉远程仓库重建一个不初始化的。方法二保留远程 README在本地执行一次允许不相关历史合并的拉取git pull origin main --allow-unrelated-histories这会在本地把远程的 README 合并进来如果出现冲突就手动解决然后 commit 并 push。我个人是强烈建议走第一条路新建仓库时不要勾选“初始化仓库”。远程仓库保持空的状态本地推上去的时候历史干净也不会出现两个 root commit 拉到一起的奇怪状态。代码托管平台的意义就是配合版本管理让 Git 决定历史该怎样生长而不是网页端帮你生成一堆多余的文件。3. 日常高频操作提交、推送、分支与标签3.1 提交推送三板斧add、commit、push 的正确打开方式关联好远程仓库之后日常开发就是一个循环改代码、暂存、提交、推送。命令就三条git status git add . git commit -m feat: 新增登录接口 git push但这里有很多细节值得说道。首先是git add .这个命令它会把当前目录下所有变更都加入暂存区包括你根本不想提交的东西。Linux 下最典型的是编译产物比如 C 语言的.o文件、Java 的target/目录、Python 的__pycache__/还有 IDE 生成的隐藏配置目录。这些东西一旦提交上去仓库会迅速变得臃肿而且相互之间合并时经常产生无意义的冲突。解决办法是在项目根目录创建一个.gitignore文件在里面写好忽略规则。以 Python 项目为例# 编译和缓存文件 __pycache__/ *.py[cod] *.o *.class # 虚拟环境 venv/ .venv/ # IDE 配置 .idea/ .vscode/ # 敏感信息 .env *.key.gitignore的规则在git add时生效被忽略的文件不会进入暂存区。这个文件一定要在第一次提交前就写好因为一旦某个文件已经被 Git 跟踪了再写进.gitignore也不会生效需要先git rm --cached 文件路径把它移出跟踪。其次是提交信息的写法。很多人图省事写111或者update短期内自己看没问题但项目过了三个月你再回头翻历史看到几十条update完全不知道当时改了什么。我的一般习惯是动词开头、说明改动目的比如git commit -m fix: 修复用户中心头像上传时偶现的404错误能一句话讲清楚就一句话讲不清楚就拆多行git commit -m feat: 新增异步任务队列 - 引入消息队列组件 - 新增任务分发模块 - 补充异常重试机制Push 之前养成习惯先看一遍git status和git diff确认要提交的就是自己想交的东西避免把还没写完的代码推上去。最后提一下git pull的使用。在多人协作的仓库里push 之前最好先拉取远程最新代码。直接git pull没问题但如果你想保持提交历史干净、线性可以用git pull --rebase origin main--rebase会把你的本地提交临时放到一边拉完远程提交后再把你自己的提交按顺序重放上去。这样历史就是一条直线。不过 rebase 在遇到冲突时会要求你逐个解决对新手稍复杂。若只想保守一点直接用默认的 merge 方式也可以功能上没有区别只是历史里会多一个 merge commit。3.2 分支操作开发隔离的利器刚开始用 Gitee 时很多人只会在main或master分支上直接提交。一个人开发这么干没问题但一旦和别人协作或者想同时开发多个不相关的功能直接在主干上提交就很容易互相打扰。Linux 下分支操作很简单# 查看当前分支和所有本地分支 git branch # 新建分支并切换过去 git checkout -b feat/login # 在新分支上正常 add、commit git add . git commit -m feat: 开发登录功能 # 把新分支推送到远程 git push -u origin feat/login # 开发完成切回主干 git checkout main # 合并新分支 git merge feat/login # 推送合并后的主干 git push # 删除已合并的本地分支 git branch -d feat/login这套流程熟练之后你可以在 Gitee 上并行维护多个功能分支比如一个分支做登录模块、一个分支做数据迁移互不干扰各自测试完再合并。远程分支的清理也很重要。分支合并后远程那个分支如果不再使用可以删掉git push origin --delete feat/login不然仓库里堆积一堆已经合并过的分支列表会越来越乱。3.3 标签与发版给重要节点做个标记如果你在维护一个对外发布的软件每次发布一个版本都值得打一个 tag。标签是 Git 对你指定的提交做一个固定引用以后想回到当时的代码状态一条命令就能搞定。# 给当前提交打标签 git tag v1.0.0 # 给指定提交打标签 git tag v1.0.0 某个commit的hash # 推送标签到远程 git push origin v1.0.0 # 查看所有标签 git tag -l # 删除本地标签 git tag -d v1.0.0 # 删除远程标签 git push origin :refs/tags/v1.0.0Gitee 的网页端会把推送过去的标签自动对应到 Release 页面你可以基于标签写发布说明管理附件等。对这个平台来说版本列表的维护其实就是 tag 的管理比单纯靠提交记录找版本省事得多。4. 常见报错与排查实录4.1 一张表解决 Linux 下 80% 的 Gitee 报错这几年在 Linux 下用 Gitee我遇到过的问题挺多但绝大多数都能归到下面几类。直接列成表格方便对号入座。报错信息原因处理方法Permission denied (publickey)SSH 公钥未绑定到 Gitee或本地私钥缺失检查~/.ssh/id_ed25519.pub是否已添加到 Gitee SSH 公钥列表执行ssh -T gitgitee.com验证fatal: refusing to merge unrelated histories本地和远程仓库各自有独立的提交历史且无共同祖先网页端重建空仓库或执行git pull origin main --allow-unrelated-histories强制合并failed to push some refs to远程有本地没有的提交通常是 README 初始化文件导致先git pull origin main解决冲突后重新 pushwarning: LF will be replaced by CRLFWindows 和 Linux 换行符不同导致的提醒在 Linux 下执行git config --global core.autocrlf input让 Git 自动处理换行符remote: HTTP Basic: Access deniedHTTPS 账号密码错误或已过期改用 SSH 地址或重新配置 HTTPS 凭据fatal: could not read Username for https://gitee.com使用 HTTPS 地址但未提供认证信息换成 SSH 地址或在 URL 中指定用户名但不要写密码fatal: detected dubious ownership in repositoryGit 检查到仓库目录归属不是当前用户常见于sudo或从其它用户目录拷贝执行sudo chown -R 当前用户名:当前用户组 /path/to/repo或用git config --global --add safe.directory /path/to/repoThe requested URL returned error: 403没有仓库写的权限常见于 fork 的仓库确认要推送到自己的仓库而不是 fork 源仓库或检查 Gitee 仓库成员权限error: src refspec main does not match any本地没有main分支但命令中指定了main先git branch看当前分支名用git branch -M main改名后重新 pushssh: connect to host gitee.com port 22: Connection refused22 端口不可达可能是网络或防火墙限制排查本地网络换 HTTPS 地址临时拉取或联系网络管理员确认端口策略这张表基本上覆盖了我日常会碰到的 80% 问题。剩下的 20% 大多和具体项目环境有关需要结合报错全文去搜但排查思路是一致的。4.2 排查通用思路从定位问题到稳定解决遇到报错我建议按以下顺序排查不要一上来就 Google 复制命令第一步看报错本身的提示。Git 的提示其实已经很友好了比如Permission denied (publickey)直接告诉你公钥有问题failed to push some refs告诉你远程有东西需要先拉取。不要怕英文捡关键的单词看就行。第二步查看远程仓库地址是否配错。执行git remote -v看一下origin的地址是不是你真正想要的那个仓库。我见过几次报错最后发现是复制地址时把别人的仓库网址粘过来了低级但很真实。第三步检查本地 Git 身份信息。执行git config --list确认user.name和user.email已经设置。假如没有设置commit 会报错或者提交记录里出现一串系统自动生成的不明身份。4.3 几个容易被忽略的实操心得第4.3节分享几个我在长期使用中总结的小心得不算教材里的标准内容但非常实用。第一个心得在 Linux 下很多人的密钥私钥权限如果太宽松SSH 会报错。出现类似UNPROTECTED PRIVATE KEY FILE的提示时执行chmod 600 ~/.ssh/id_ed25519让私钥只允许当前用户读写就够了。这是 Linux 的安全机制别把它关掉。第二个心得别把带密码的文件提交到 Gitee 仓库。.env、数据库密码、云平台密钥这类东西一旦进了 Git 历史即使后面删掉历史记录里仍然可以翻出来。如果已经发生了不只是删文件还要清理历史或者直接换密钥。这个教训我身边有人经历过代价很大。第三个心得用命令行时多按 Tab 键自动补全。git cheTab会补全成git checkout在你不太记得完整命令的时候特别好用。补全列表还会显示子命令和分支名某种程度上就是内置帮助。第四个心得是养成提交前测试的习惯。在本地先把能跑的测试跑一遍再执行git add和git commit。不然你推上去的代码和在草稿箱里放着的没两样只是换了个地方丢人。5. 谈谈我对 Gitee 托管流程的整体体会最后说几句心里话。我用 Gitee 托管代码的时间不算短踩过的坑也远不止上面列出来的这些。但正因为踩过现在反而觉得把这套流程理解透了其实比用任何图形界面都轻松。最大的体会是Git 本身是一个本地优先的工具Gitee 远程仓库只是你本地历史的一个备份和协作点。很多人在 Linux 下用 Gitee 不顺手是因为把远程仓库当成了唯一重要的东西整天纠结 push 和 pull却忽略了本地提交、分支、标签这些真正属于 Git 的核心能力。另一个体会是不必要的东西别往上放。README、.gitignore、许可证文件这些可以放编译产物、缓存文件、密钥文件、大体积的二进制包就别放。仓库保持干净不只是好看对 clone 速度和后续协作都有好处。还有个小技巧顺手分享如果同时在多台 Linux 机器上开发可以在一台机器上配置好后把~/.ssh/里的密钥文件复制到另一台机器并把公钥都加到 Gitee 账号里。这样几台机器都能免密推送省掉了给每台机器单独生成公钥绑定的麻烦。不过复制私钥时注意用安全的方式走加密通道别明文发群里。这套流程走通之后你会发现原来给代码找个家真的就是二十分钟的事。剩下的时间安心写代码就好。