Linux下Gitee使用实战：从SSH认证到PR协作的完整避坑指南

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 -y

• CentOS / RHEL 系（旧版用yum，新版用dnf）：

sudo yum install git -y # 或者 sudo dnf install git -y

• Arch 系：

sudo pacman -S git

装完后再敲一次git --version确认一下。我一般会顺手把这个版本号记下来，因为git老版本和新版本的默认行为差异挺大，后面如果发现某些命令行为怪怪的，第一步就该怀疑是版本差异导致的问题，而不是配置错误。

1.2 配置用户信息、默认分支与换行符

git提交记录里的作者信息不是系统自动识别的，它完全来自全局配置。如果你不配置就提交，git会用系统用户名和主机名拼一个默认值出来，提交记录会显示成root@hostname这种“路人名”，在Gitee上关联不到你的账号，主页上也不会有贡献记录。

所以装完git后的第一件事，是配置全局用户名和邮箱：

git config --global user.name "你的名字" git config --global user.email "你的邮箱"

这里有个关键细节：邮箱最好和Gitee注册邮箱保持一致。Gitee是依靠邮箱把本地提交关联到账号的，如果两边邮箱对不上，就算push成功了，提交记录在Gitee网页上也显示不出你的头像和用户名。

接下来设置默认分支名。以前git创建仓库的默认分支叫master，现在很多托管平台把默认分支改成了main，Gitee新建仓库默认也是main。为了保证本地和远端保持一致，提前设置一下：

git config --global init.defaultBranch main

这个配置非常容易被忽略，但后果很烦人：不设的话，本地git init创建的仓库默认分支是master，推送到Gitee之后会在远端形成master和main两个默认分支并存的局面，还得手动删除一个，操作起来很别扭。

再就是换行符配置，这是跨平台协作最容易踩的坑之一。Linux和Windows开发者混编项目时，CRLF（Windows换行符）和LF（Unix换行符）会反复打架。在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 --timeout=3600'

这样凭据只在内存里缓存一小时，时间到了就失效重输入。

顺带说下别名。用别名的确能让命令行舒服很多，我常用的几个是：

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地址，很多人会纠结选哪个。这两种方式各有适用场景，我整理了一个对比表：

我个人的主力选择是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 git@gitee.com

第一次连接会提示确认host key，输入yes后，如果看到类似“Hi xxx! You've 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服务端只认git@gitee.com这个路径，个人账号对应的Host是gitee-personal.com，那本地操作个人仓库时，remote地址必须写成git@gitee-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 git@gitee.com:用户名/仓库名.git # 或者 git clone https://gitee.com/用户名/仓库名.git

如果希望克隆到指定目录，可以在后面加路径参数：

git clone git@gitee.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: 更新README

feat、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 pull

git 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. 团队协作里的 Gitee：PR、Issue 与保护分支的使用心得

4.1 一次完整的 PR 流程

Gitee的核心协作方式是Pull Request（简称PR），整个流程已经相当成熟：

1. 从主干拉一条特性分支
2. 在分支上完成提交并push到远端
3. 在Gitee仓库页面点击“新建PR”，选择源分支（特性分支）和目标分支（如main）
4. 填写PR标题和描述，关联Issue
5. 等待review意见和CI检查结果，最终合并

进程上跟其它托管平台差不多，但有两点细节值得提。第一，PR描述里用#issue编号可以自动关联Issue，比如写fix #23，PR合入后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的Issue，Gitee也没有提供类似官方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 git@gitee.com # 第二步：确认ssh-agent加载了哪些密钥 ssh-add -l # 第三步：用指定的密钥文件强制验证 ssh -T -o IdentitiesOnly=yes -i ~/.ssh/id_ed25519_gitee git@gitee.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 = 60

postBuffer是HTTP协议下提交数据的缓冲区大小，默认值较小，大对象推送时容易触发缓冲不足。提高它可以让大文件推送更稳。lowSpeedLimit和lowSpeedTime默认是0，不生效；按上面的配置，当传输速度持续15秒低于4KB/s时才允许断线，稍微增加了一点容错空间。

注意postBuffer不是越大越好，它会增加内存占用，尤其是并发push多个大仓库时，建议按实际情况调整而不是无脑拉满。

如果网络实在不稳，还有一个笨办法：把大的改动拆成多个小commit逐步push，别一次性塞一个巨无霸提交进去。

5.3 单文件过大或仓库体积失控

Gitee对单文件大小有明确限制，超出限制push会直接报错。更隐蔽的问题是：历史提交里已经包含了体积巨大的文件，就算后来删掉了，历史记录里依然存在，仓库体积会越来越臃肿。

处理这类问题，需要重写历史。比较快的工具是git filter-repo：

pip 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文件，强制统一所有协作者的换行符行为：

* text=auto *.sh text eol=lf *.bat text eol=crlf

这个文件提交到仓库后，所有协作者clone时都会自动应用，比让大家手动改config靠谱得多。text=auto表示git自动检测文本文件并统一转换；eol=lf和eol=crlf则分别指定特定后缀文件的换行符格式，比如脚本必须保持LF。

5.5 SSH 连接卡住超时的处理

在部分网络环境下，SSH的22端口可能被限制，连接会卡很久然后超时。如果你执行ssh -T git@gitee.com长时间无响应，可以给SSH客户端配置更短的连接超时：

echo "ConnectTimeout 10" >> ~/.ssh/config

把默认的等待时间缩短到10秒，失败就能快速感知，不用干等几十年。

Gitee还提供443端口SSH服务，如果22端口不通，可以改用443端口：

ssh -T -p 443 git@gitee.com

仓库的remote地址也需要改成带端口的SSH格式：

git clone ssh://git@ssh.gitee.com:443/用户名/仓库名.git

443端口通常不会被默认业务防火墙拦截，是一个比较实用的替代方案。我在一处锁了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做代码托管，希望这份经验能帮你少走一点弯路。