Gitee在Linux下使用这件事很多教程只讲到“装上git、配好SSH密钥、push/pull”就结束了但真正上手后你会发现坑基本都在文档之外。我前前后后把一台Linux开发机作为主力机器来管理Gitee仓库踩过公钥不对、多账号冲突、大文件推送超时、换行符被反复转换等各种问题也把团队项目的PR流程完整走了一遍。这篇不打算复读官方文档就把我从零开始的配置过程、选型取舍、日常操作规范以及踩坑后的排查思路都沉淀出来希望对正在Linux上折腾Gitee的同学有帮助。1. 环境准备先让 Git 在你机器上“活”起来1.1 检查与安装 Git 的几种方式拿到一台新的Linux机器不管是云服务器还是本地虚拟机第一件事永远是确认git是否已经存在。直接在终端里敲git --version如果输出类似git version 2.43.0这样的信息说明系统里已经有git了可以直接用。如果提示command not found就需要自己装。这里我强烈建议优先使用发行版自带的软件源安装别一上来就去官网下载源码编译。软件源里的版本经过了打包测试依赖关系处理得干净以后升级也方便。不同发行版的安装命令不太一样我列一下常用的Debian / Ubuntu 系sudo apt update sudo apt install git -yCentOS / RHEL 系旧版用yum新版用dnfsudo yum install git -y # 或者 sudo dnf install git -yArch 系sudo pacman -S git装完后再敲一次git --version确认一下。我一般会顺手把这个版本号记下来因为git老版本和新版本的默认行为差异挺大后面如果发现某些命令行为怪怪的第一步就该怀疑是版本差异导致的问题而不是配置错误。1.2 配置用户信息、默认分支与换行符git提交记录里的作者信息不是系统自动识别的它完全来自全局配置。如果你不配置就提交git会用系统用户名和主机名拼一个默认值出来提交记录会显示成roothostname这种“路人名”在Gitee上关联不到你的账号主页上也不会有贡献记录。所以装完git后的第一件事是配置全局用户名和邮箱git config --global user.name 你的名字 git config --global user.email 你的邮箱这里有个关键细节邮箱最好和Gitee注册邮箱保持一致。Gitee是依靠邮箱把本地提交关联到账号的如果两边邮箱对不上就算push成功了提交记录在Gitee网页上也显示不出你的头像和用户名。接下来设置默认分支名。以前git创建仓库的默认分支叫master现在很多托管平台把默认分支改成了mainGitee新建仓库默认也是main。为了保证本地和远端保持一致提前设置一下git config --global init.defaultBranch main这个配置非常容易被忽略但后果很烦人不设的话本地git init创建的仓库默认分支是master推送到Gitee之后会在远端形成master和main两个默认分支并存的局面还得手动删除一个操作起来很别扭。再就是换行符配置这是跨平台协作最容易踩的坑之一。Linux和Windows开发者混编项目时CRLFWindows换行符和LFUnix换行符会反复打架。在Linux上我推荐这样设置git config --global core.autocrlf input它的作用是提交时把CRLF转换成LF存入仓库checkout时不做反向转换。Windows端再设置core.autocrlf true两边就能和平共处。这个背后逻辑是让仓库里永远只保存LF各平台按自己的习惯去做转换列到后面第5章我会再展开说。1.3 配置凭据缓存与常用别名如果后面你打算用HTTPS方式连接Gitee具体选型对比见第2章每次push都输入用户名密码会非常折磨人。配置一下凭据存储git config --global credential.helper store这样第一次输入用户名密码后会被明文存储在~/.git-credentials文件里以后就不用重复输入了。如果机器安全性要求高不想明文存可以改用cache模式并设置过期时间git config --global credential.helper cache --timeout3600这样凭据只在内存里缓存一小时时间到了就失效重输入。顺带说下别名。用别名的确能让命令行舒服很多我常用的几个是git config --global alias.co checkout git config --global alias.br branch git config --global alias.st status但刚开始不建议配太多花哨的别名先把原生命令记熟了后面自然知道自己最需要简写哪些。2. SSH 与 HTTPS 认证Gitee 的两种连接方式怎么选、怎么配2.1 两种方式的核心区别Gitee仓库页面会同时给出HTTPS和SSH两种clone地址很多人会纠结选哪个。这两种方式各有适用场景我整理了一个对比表对比维度HTTPSSSH配置难度低首次输入令牌即可中等需要生成密钥并上传公钥日常push体验需要配置凭据存储否则反复验证配置好后完全免密最省心安全性凭据在传输层加密服务器侧凭据可撤销私钥只存在本地公钥认证更安全网络限制一般无碍如果防火墙屏蔽22端口连接会失败我个人的主力选择是SSH。尤其是长期使用的开发机一次性配置好之后push、pull、fetch全程免密体验非常顺畅。HTTPS则适合临时借用的机器或者不熟悉密钥概念的场景用访问令牌方式也能快速上手。2.2 SSH密钥生成与公钥添加的完整步骤在Linux终端生成SSH密钥一行命令就够了ssh-keygen -t ed25519 -C gitee-ssh-key -f ~/.ssh/id_ed25519_gitee这里解释一下参数含义-t ed25519指定密钥算法为Ed25519这是目前推荐的新一代算法密钥短、生成快、安全性高。如果你需要连接一些只支持RSA的老旧系统可以改用-t rsa -b 4096。-C是注释通常填你的标识信息方便区分是哪台机器。-f指定私钥的保存路径。执行过程中会提示输入passphrase口令这个相当于给私钥再加一道密码锁。我建议开发机上设置一个虽然每次加载密钥时多一步输入但万一私钥文件泄露没有口令别人也拿它没办法。生成完成后启动ssh-agent把私钥添加进去eval $(ssh-agent -s) ssh-add ~/.ssh/id_ed25519_gitee查看公钥内容cat ~/.ssh/id_ed25519_gitee.pub会输出一整行以ssh-ed25519开头的字符串把这个字符串完整复制下来。然后登录Gitee网页端进入 个人设置 - 安全设置 - SSH公钥把内容粘贴进去标题随便填比如“Linux办公机”。点击保存公钥添加就算完成了。验证一下是否配置成功ssh -T gitgitee.com第一次连接会提示确认host key输入yes后如果看到类似“Hi xxx! Youve successfully authenticated”的欢迎消息说明公钥已经生效可以直接连接Gitee了。2.3 多账号场景下的 SSH 配置很多人会遇到同机器上需要管理两个Gitee账号的情况比如公司一个号、个人一个号。这种情况下不能只靠一套默认密钥因为默认密钥会和两个账号都对不上。解决办法是借助~/.ssh/config文件做区分# 公司账号 Host gitee.com HostName gitee.com User git IdentityFile ~/.ssh/id_ed25519_company # 个人账号使用别名Host Host gitee-personal.com HostName gitee.com User git IdentityFile ~/.ssh/id_ed25519_personal这里有个需要注意的陷阱Gitee服务端只认gitgitee.com这个路径个人账号对应的Host是gitee-personal.com那本地操作个人仓库时remote地址必须写成gitgitee-personal.com:用户名/仓库.git。如果你在克隆个人仓库时用的是网页上复制下来的标准地址它只会指向默认的gitee.com不会动用个人私钥。如果不想折腾这个Host别名机制也有个更省事的替代方案个人仓库全部走HTTPS 访问令牌公司仓库走SSH。两条路用同一个Git客户端完全没问题git会自动根据URL前缀选择合适的认证方式。2.4 HTTPS方式下用访问令牌替代密码Gitee现在对HTTPS方式直接使用账号密码的限制越来越严格推荐的方式是用私有令牌Personal Access Token。生成路径是Gitee网页端 - 个人设置 - 私人令牌 - 生成新令牌勾选需要的权限范围一般仓库相关的读写权限就够用了。生成后复制那串令牌在命令行push时用户名输入Gitee账号密码输入这串令牌即可。如果前面配置过credential.helper store第一次输入之后就会被缓存后续不再需要重复输入。2.5 我的认证选型建议不只是技术层面选型还涉及团队协作习惯。如果团队都是Linux重度用户直接统一用SSH大家都配好自己的公钥维护成本极低。如果团队里有一些人不习惯命令行或密钥概念HTTPS 令牌是更友好的起点。我的建议是两条路都配好。主力开发机上SSH公钥上传到Gitee偶尔临时用的机器上HTTPS 令牌。这样环境不管怎么变都不会被认证方式卡住。3. 克隆、分支、提交与推送Linux 命令行下的完整日常流程3.1 克隆仓库与仓库初始化细节从Gitee仓库页面复制地址有HTTPS和SSH两种格式对应两种clone方式git clone gitgitee.com:用户名/仓库名.git # 或者 git clone https://gitee.com/用户名/仓库名.git如果希望克隆到指定目录可以在后面加路径参数git clone gitgitee.com:用户名/仓库名.git ~/projects/仓库名克隆完成后进入目录我习惯先确认仓库状态和最近提交记录cd 仓库名 git status git log --oneline -5这样能快速判断当前仓库是从哪里、基于什么版本克隆出来的后续操作心里有底。3.2 创建分支、推送分支与删除分支团队协作里最常见的操作就是建分支。从主干拉一条特性分支git checkout -b feature/login-page新版本git也支持git switch语法git switch -c feature/login-page写完之后提交。提交信息我强烈建议遵循一个基本约定第一行写类型加简述比如feat: 增加登录页面 fix: 修复空指针异常 docs: 更新READMEfeat、fix、docs前缀能让人扫一眼提交历史就明白这次改动的性质。Gitee的PR界面会直接展示这些提交信息好的提交信息相当于免费的文档。具体提交命令git add . git commit -m feat: 增加登录页面这里提醒一句git add .会把当前目录所有改动都加进去包括不该提交的临时文件。正确习惯是先git status看清楚改了哪些再精确添加或者靠.gitignore把临时文件排除掉。具体配置规范见3.4小节。推送分支到远端第一次带-u参数建立跟踪关系git push -u origin feature/login-page以后这个分支再push就不需要带任何参数了。删除分支的操作分本地和远端两步git branch -d feature/old-branch git push origin --delete feature/old-branch注意-d只会删除已合并入主干的分支如果分支有未合并的提交git会拒绝删除并提示这是保护机制。要强制删除得用-D慎用。3.3 拉取最新代码、合并与处理冲突多人协作的项目里推送前第一件事就是拉取最新代码否则很可能遇到远端领先本地的情况。最朴素的做法git pullgit pull默认执行fetch merge。如果本地没有未提交的改动通常没问题但如果本地正好也在改自动合并可能会触发冲突甚至会创建额外的merge提交。我更喜欢先把远端状态拉下来再决定怎么合并git fetch origin git checkout main git rebase origin/main先fetch把远端状态拉下来用rebase把本地提交变基到最新commit之上。这样提交历史是线性的PR合并时清爽得多不会出现一堆意义不明的merge节点。冲突处理是新人最容易紧张的地方。比如本地和远端同时改了同一个文件的同一行合并时会报CONFLICT文件内容会变成这样 HEAD 本地内容 远端内容 origin/main处理方式是手动编辑这个文件保留正确内容删掉冲突标记行然后git add 冲突文件 git commit -m fix: 解决与远端main分支的冲突如果编辑错了怎么办不用慌git的reflog能帮你找回之前的提交状态git reflog它记录了你在仓库里的每一次HEAD变动就算冲突处理到一半发现改坏了也可以找到之前的状态恢复。3.4 用 .gitignore 管理不需要提交的文件Linux下很容易产生各种临时文件vim的swap文件、build目录、IDE配置、日志文件。如果这些被push到Gitee不仅污染仓库还会拖慢clone速度。规范做法是在仓库初始化时就写好.gitignore。以Python项目为例__pycache__/ *.py[cod] .venv/ venv/ .env dist/ build/ *.log .idea/ .vscode/Node项目则不一样node_modules/ dist/ .logs/ .env.local .idea/ .vscode/这里强调一个细节.gitignore只对尚未被git跟踪的文件生效。如果已经把某个文件提交进了仓库再往.gitignore里加也没用。需要先把文件移出版本控制git rm -r --cached 目录名--cached参数表示只从版本控制中移除不删除本地文件。移除后再提交push远端仓库里就不再有这个文件了。4. 团队协作里的 GiteePR、Issue 与保护分支的使用心得4.1 一次完整的 PR 流程Gitee的核心协作方式是Pull Request简称PR整个流程已经相当成熟从主干拉一条特性分支在分支上完成提交并push到远端在Gitee仓库页面点击“新建PR”选择源分支特性分支和目标分支如main填写PR标题和描述关联Issue等待review意见和CI检查结果最终合并进程上跟其它托管平台差不多但有两点细节值得提。第一PR描述里用#issue编号可以自动关联Issue比如写fix #23PR合入后Issue会自动关闭效果非常省事。第二Gitee会把PR里所有提交的commit信息聚合展示所以前面说的提交信息规范在PR场景里会直接放大价值。4.2 在命令行查看远端 PR 分支有些PR改动量大在网页上逐个文件点开看不方便。可以把PR分支拉下来在本地验证。Gitee的PR分支一般可以通过仓库的refs/pull路径拿到git fetch origin refs/pull/123/head:pr-123 git checkout pr-123当然不同项目对PR引用路径的配置可能不同实际以Gitee页面给出的参考命令为准。本地验证通过后再切回主干分支继续正常操作。4.3 保护分支配置与合并策略在Gitee的 仓库设置 - 分支设置 里可以对main分支开启保护。保护一旦开启普通成员就不能直接push到main必须通过PR合并。还可以进一步勾选“需要审核通过后合入”“合并前必须通过CI检查”等选项。合并策略一般有三种merge commit保留所有提交历史适合重视完整开发过程的团队Squash合并将PR内所有提交压缩成一个提交适合业务迭代快、PR内垃圾提交多的团队Rebase合并将PR提交变基后合入历史最干净但没有独立merge节点我个人的观点是选merge commit还是squash没有一个绝对正确答案关键看团队是否习惯清理提交历史。但不管选哪种一旦定了就要保持一致否则分支历史会混乱。4.4 Issue 管理的基本约定很多人把Issue当bug tracker用实际上Gitee的Issue完全可以承担轻量级项目管理。我们团队的约定是这样的bug类Issue标题直接写现象描述里带上运行环境、复现步骤、期望结果需求类Issue描述里写清楚用户场景、验收标准所有Issue尽量打标签bug / feature / enhancement 等整改Issue状态这类操作在网页端很顺手因为git原生命令并不支持操作Gitee的IssueGitee也没有提供类似官方CLI工具。所以实际协作中网页端是绕不开的一环。我的原则是尽量把网页操作收敛在最小集合看PR状态、评论代码、开Issue、合并操作其余全部用命令行完成。4.5 团队协作里的一点体会早期我们一起做项目时有人图省事直接向main push结果每次发布前都要做大量合并冲突现场惨不忍睹。后来强制改成PR流reviewer能看到的就不再只是“这行写错了”这类低级问题更多是“这个设计方案是否值得再优化一下”的讨论。这个过程才是代码托管平台真正的价值——把协作变成代码质量的增量。5. 踩坑与排查Linux 下连接 Gitee 的常见问题与解决思路5.1 Permission denied (publickey) 排查要说Gitee用户遇到频率最高的错误莫过于push时提示Permission denied (publickey)。现象千篇一律但原因多种多样我的排查顺序是# 第一步确认当前SSH能连上Gitee不 ssh -T gitgitee.com # 第二步确认ssh-agent加载了哪些密钥 ssh-add -l # 第三步用指定的密钥文件强制验证 ssh -T -o IdentitiesOnlyyes -i ~/.ssh/id_ed25519_gitee gitgitee.com如果ssh-add -l是空的说明agent没有加载密钥执行ssh-add ~/.ssh/id_ed25519_gitee如果还是没有效果再检查~/.ssh/config里的IdentityFile路径是不是指向了不存在的文件或者公钥是不是真的添加到了Gitee后台。还有一个容易被忽略的点服务器系统时间如果偏差过大会影响SSH认证用date命令确认一下时间。5.2 断线重推与带宽受限场景在Linux服务器上拉取大仓库或推送大文件时偶尔会遇到connection reset。尤其是push几百MB的分支传到一半断开再次push又要从头开始。为了减少这种风险可以在仓库的.git/config或全局配置里增加[http] postBuffer 524288000 lowSpeedLimit 1000 lowSpeedTime 60postBuffer是HTTP协议下提交数据的缓冲区大小默认值较小大对象推送时容易触发缓冲不足。提高它可以让大文件推送更稳。lowSpeedLimit和lowSpeedTime默认是0不生效按上面的配置当传输速度持续15秒低于4KB/s时才允许断线稍微增加了一点容错空间。注意postBuffer不是越大越好它会增加内存占用尤其是并发push多个大仓库时建议按实际情况调整而不是无脑拉满。如果网络实在不稳还有一个笨办法把大的改动拆成多个小commit逐步push别一次性塞一个巨无霸提交进去。5.3 单文件过大或仓库体积失控Gitee对单文件大小有明确限制超出限制push会直接报错。更隐蔽的问题是历史提交里已经包含了体积巨大的文件就算后来删掉了历史记录里依然存在仓库体积会越来越臃肿。处理这类问题需要重写历史。比较快的工具是git filter-repopip install git-filter-repo git filter-repo --path 大文件名 --invert-paths--invert-paths表示排除指定路径把这行写反就会变成只保留指定路径。注意filter-repo会重写所有历史commit导致所有协作者的本地仓库与远端不再一致使用后团队成员需要重新clone。更推荐的做法是防患于未然在仓库初始化阶段就约定好二进制产物放对象存储或制品库代码仓库只放源码和脚本。Gitee提供发行版文件和Attachments功能可以用在二进制分发场景而不是把它塞进git仓库。5.4 CRLF 换行符问题的经典现场团队里有人用Windows、有人用Linux时最经典的现象是git diff显示某个文件整个文件都是改动而且只改了其中一行。底层原因基本都是autocrlf配置不一致导致换行符在本地反复被转换git无法准确识别差异。单靠前面说的core.autocrlf input并不能覆盖所有情况因为每个协作者都有自己的全局配置。最可靠的办法是在仓库根目录放一个.gitattributes文件强制统一所有协作者的换行符行为* textauto *.sh text eollf *.bat text eolcrlf这个文件提交到仓库后所有协作者clone时都会自动应用比让大家手动改config靠谱得多。textauto表示git自动检测文本文件并统一转换eollf和eolcrlf则分别指定特定后缀文件的换行符格式比如脚本必须保持LF。5.5 SSH 连接卡住超时的处理在部分网络环境下SSH的22端口可能被限制连接会卡很久然后超时。如果你执行ssh -T gitgitee.com长时间无响应可以给SSH客户端配置更短的连接超时echo ConnectTimeout 10 ~/.ssh/config把默认的等待时间缩短到10秒失败就能快速感知不用干等几十年。Gitee还提供443端口SSH服务如果22端口不通可以改用443端口ssh -T -p 443 gitgitee.com仓库的remote地址也需要改成带端口的SSH格式git clone ssh://gitssh.gitee.com:443/用户名/仓库名.git443端口通常不会被默认业务防火墙拦截是一个比较实用的替代方案。我在一处锁了SSH端口的生产网环境里就是用这种方式保持连接的。5.6 无法初始化本地仓库与远端推送失败有时候新建了本地目录执行git init后直接把目录下的所有文件git add再git commit想推送到Gitee新建的空仓库却发现远端已经有README或LICENSE文件导致push被拒绝。这是因为你在Gitee端新建仓库时勾选了“初始化README”远端和本地的历史没有任何关联。处理方式是先pull远端允许不相关历史合并git pull origin main --allow-unrelated-histories把两边的历史拼接起来再处理冲突后push。如果不需要远端的README直接在Gitee网页把README删除后再push也是一条路。我在实际开发中还养成一个习惯本地初始化仓库时先建一个内容齐全的README再关联远端这样空仓库push时不会因为缺少首个文件而出现各种边界情况。一些实际操作层面的补充建议在Linux下持续使用Gitee一段时间后我总结出几个日常习惯分享出来也许对你有参考价值。一个是收敛分支数量。Gitee仓库的分支越多网页端列表越难管理本地也容易搞混。我通常维持三条长期分支如main、dev、release其余特性分支用完即删。删得多、建得快反而比长期保留一堆没合并的分支更安全。另一个是提交频率。本地开发时保持小步提交一个功能点一次commit绝不攒到下班才一次性提交。这样做的好处是出问题时git bisect可以精确找到引入bug的提交比大海捞针式排查效率高一个量级。Gitee的过程评审也依赖这些commit粒度。还有一个是留意push前先fetch。就算你觉得没人动过这个分支也先git fetch看看远端状态尤其在你的分支已经存在一段时间后。一次顺手操作可能避免一次尴尬的rebase冲突现场。最后说说备份意识。Gitee仓库虽然是远程托管但它不是备份工具。我遇到过把个人脚本和论文草稿也推到Gitee私有仓库的情况后来觉得不合适更合理的用法是代码仓库保持代码的纯粹性重要非代码资产单独走文件存储或私有网盘。这次分享的内容覆盖面比较广从环境初始化、认证方式选型到命令行协作规范再到高频踩坑的排查思路基本是我在Linux下使用Gitee全流程的沉淀。如果你正处于把开发环境迁到Linux的阶段或者团队刚准备切换到Gitee做代码托管希望这份经验能帮你少走一点弯路。
