团队 Gitee 免登录协作指南（Windows / macOS）

团队 Gitee 免登录协作指南（Windows / macOS）

这份指南解决什么问题

配置一次之后，团队成员就能在 IDE（Qoder / Trae）里直接拉取、修改、提交代码与文档，全程不需要打开 Gitee 网页、也不需要输入账号密码——不必再登录网页去点”上传文件 / 新建文档 / 在线编辑”。

原理是用 SSH 密钥代替账号密码：一次配置、长期有效，不会像”令牌（token）“那样过期，也不会再遇到 403 / Access token is expired 报错。

📌 “免登录”的准确含义：日常的拉取 / 提交操作不再需要登录网页；首次配置时仍需登录一次 Gitee 网页粘贴公钥（见第 6 步），且需已被项目负责人加为仓库协作者。

全文按顺序照做即可，每一步都写明了”预期看到什么”，看到不一样就查第七节的排查表。

开始之前，先确认两件事

#	需要确认的事	怎么确认
1	你有 Gitee 账号，并且已被加为本项目的协作者	问项目负责人。⚠️ 本项目是私有仓库，没被加协作者，后面第 8 步克隆一定会失败
2	电脑上装了 git	终端里执行 git --version，能显示版本号（如 git version 2.4x）就行

如果第 2 项报错”找不到命令”：Windows 上重开一次 IDE（Qoder 或 Trae）再试（它们通常自带 git）；仍不行就联系项目负责人。

项目负责人会给你一个仓库地址，格式形如： git@gitee.com:<组织名>/<仓库名>.git

⚠️ <组织名> 和 <仓库名> 是占位符，请替换成负责人给你的真实内容，不要原样照抄。

30 秒看懂原理

SSH 就是给 Gitee 挂一把锁，你手里留一把钥匙：

名称	类比	放在哪	能否外发
公钥	锁	挂到你的 Gitee 账号上	✅ 可以（本来就是给别人的）
私钥	钥匙	只存在你自己电脑里	❌ 绝对不能发给任何人

配置好之后，每次操作 Gitee 只会问一句”你手里的钥匙能开我门上的锁吗”，能开就放行。

为什么不直接用账号密码？

Gitee 不允许用登录密码做代码操作。另一条路是用”令牌（token）“，但令牌有有效期、会过期（过期后就会报 403 或 Access token is expired）。SSH 钥匙没有有效期，配一次就一劳永逸——所以本指南推荐 SSH。

Windows 操作步骤（第 1 ~ 8 步）

第 1 步 · 打开 PowerShell

按下 Win 键 → 输入 powershell → 回车。

（用 Qoder / Trae 内置的终端也可以，效果一样。下面的命令都可以直接复制粘贴。）

第 2 步 · 检查系统是否已带 SSH

ssh -V

• 显示 OpenSSH_for_Windows_x.x → ✅ 已有，继续第 3 步
• 提示”无法将 ‘ssh’ 项识别为…” → 需要安装： 设置 → 应用 → 可选功能 → 添加功能 → 搜索 OpenSSH 客户端 → 安装 → 重开 PowerShell 再执行一次 ssh -V

第 3 步 · 登记你的身份

git config --global user.name "你的名字"
git config --global user.email "你在Gitee注册时用的邮箱"

⚠️ 邮箱必须是 Gitee 账号里的邮箱，否则提交到 Gitee 后不会显示成”是你提交的”。 不知道自己用哪个邮箱？登录 Gitee → 右上角头像 → 设置 → 邮箱管理 里能看到。

第 4 步 · 生成钥匙（公钥 + 私钥）

ssh-keygen -t ed25519 -C "你在Gitee注册时用的邮箱"

接下来会依次提问，正常情况下都是直接按回车：

提示	怎么答
Enter file in which to save the key (...)	回车（用默认位置）
Enter passphrase (empty for no passphrase)	回车（密码留空）
Enter same passphrase again	回车
❗ 如果出现 ... already exists. Overwrite (y/n)?	说明电脑上已有一对钥匙。先别覆盖，输入 n 回车，然后直接跳到第 5 步（你已经有钥匙了，直接用现成的）

⚠️ 请在普通 PowerShell 里执行，不要用「以管理员身份运行」。管理员模式下生成的钥匙会存到管理员账号的目录里，之后正常使用时找不到，表现为 Permission denied (publickey)。

生成后，钥匙在你的用户目录下的 .ssh\ 文件夹里（通常是 C:\Users\你的用户名\.ssh\，精确写法是 $env:USERPROFILE\.ssh）：

• id_ed25519 —— 私钥（钥匙），绝不外发
• id_ed25519.pub —— 公钥（锁），下一步要复制它

第 5 步 · 复制公钥

Get-Content "$env:USERPROFILE\.ssh\id_ed25519.pub" | Set-Clipboard

执行后没有任何提示就是成功了，公钥已在剪贴板里。

如果提示 Set-Clipboard 不存在（系统太老），改用这条，用记事本打开后 Ctrl+A 全选 → Ctrl+C 复制：

notepad "$env:USERPROFILE\.ssh\id_ed25519.pub"

第 6 步 · 把锁挂到 Gitee

1. 浏览器打开：https://gitee.com/profile/sshkeys
2. 点「新增公钥」
3. 标题：随便填（例如”我的办公电脑”）
4. 公钥：Ctrl+V 粘贴第 5 步复制的内容（末尾多一个换行没关系）
5. 点「确定」，按提示输入 Gitee 登录密码完成验证

第 7 步 · 验证是否成功（★ 全流程唯一检查点）

ssh -T git@gitee.com

第一次会问一句：

The authenticity of host 'gitee.com (...)' can't be established.
Are you sure you want to continue connecting (yes/no/[fingerprint])?

→ 输入 yes 回车（正常现象，只是第一次确认服务器身份，以后不再问）。

看到下面这句就代表 ✅ 成功：

Hi 你的用户名! You've successfully authenticated, but GITEE.COM does not provide shell access.

判断标准是看这句话，不要去看”报错/退出码”之类的提示——Gitee 会附带一句 “does not provide shell access”，那是正常的，不是错误。

第 8 步 · 下载代码

先切到桌面（这样代码会出现在你一眼能看到的地方）：

cd $env:USERPROFILE\Desktop
# 注意：下面一行里的 <组织名> 和 <仓库名> 需替换成负责人给你的实际内容
git clone git@gitee.com:<组织名>/<仓库名>.git

桌面上会出现一个以仓库名命名的文件夹（即上一步 <仓库名> 的位置），即下载完成。

若报 Repository not found 或 403：说明第一件事没办成——你还没被加为本项目协作者，联系项目负责人添加后重试。

macOS 操作步骤

与 Windows 完全一致（同样是第 1~8 步），只有 3 处不同：

环节	Windows	macOS
第 1 步 打开终端	Win → powershell	Command + 空格 → 输入 终端 / Terminal
第 2 步 检查 SSH	（可能需安装）	ssh -V 即可（macOS 自带）
第 5 步 复制公钥	Get-Content "$env:USERPROFILE\.ssh\id_ed25519.pub" | Set-Clipboard	pbcopy < ~/.ssh/id_ed25519.pub
第 8 步 切到桌面	cd $env:USERPROFILE\Desktop	cd ~/Desktop

其余命令一字不差照抄。macOS 的钥匙同样在 ~/.ssh/ 下：id_ed25519（私钥）、id_ed25519.pub（公钥）。

下载代码 → 用 IDE 打开 → 看代码 → 提交代码

本节以 Qoder 为例；Trae 的操作与界面基本一致，照着做即可。

先下载（克隆）代码

“克隆”就是把 Gitee 上的完整代码复制一份到你电脑上。

✅ 如果你已经执行过第三节第 8 步，代码已经下载好了，直接跳到下文”用 IDE 打开项目”，不必重复。

任选一种方式下载：

方式 A｜命令行（推荐，一定可用）——就是第三节第 8 步的那条命令：

cd $env:USERPROFILE\Desktop
git clone git@gitee.com:<组织名>/<仓库名>.git

macOS 用户把第一行换成 cd ~/Desktop；再把 <组织名>/<仓库名> 换成实际内容。

方式 B｜IDE 图形界面：在 Qoder 或 Trae 的欢迎页点「克隆仓库」；或按 Ctrl+Shift+P 打开命令面板，输入 Git: Clone，把 git@gitee.com:<组织名>/<仓库名>.git 粘进去，再选一个本地保存位置。

（不同版本的菜单位置可能略有差异；方式 A 一定可用。）

用 IDE 打开项目

Qoder / Trae → 文件 → 打开文件夹 → 选择上一步下载出来的 <仓库名> 目录

看代码

左侧文件树直接浏览；有改动的文件会自动高亮。

提交代码

1. 点左侧边栏的「源代码管理」图标（快捷键 Ctrl+Shift+G，Mac 为 Cmd+Shift+G）
2. 在输入框写一句提交说明
3. 点「✔ 提交」
4. 再点「同步 / 推送」即可推送到 Gitee

全程不会弹窗要账号密码——因为钥匙已经在后台默默工作了。

完成自检清单

全部打勾即为配置成功：

• git --version 能显示版本号
• ssh -T git@gitee.com 显示 Hi 你的用户名! ...
• 第 8 步克隆出来的文件夹里有 README.md
• 用 Qoder / Trae 打开该文件夹后，左侧能看到「源代码管理」面板
• 在 Qoder / Trae 里随便改一个字 → 提交 → 推送，Gitee 网页上能看到这条提交，且显示的是你的头像/名字
• 以上全过程没有要求你输入账号密码，也没有让你打开 Gitee 网页（首次粘贴公钥那次除外）——达到本指南的目标

常见问题排查

现象	原因	解决办法
ssh: command not found / 无法识别	Windows 没装 OpenSSH 客户端	回到第 2 步安装
Permission denied (publickey)	公钥没挂到 Gitee / 挂到了别的账号 / 用了「管理员身份」生成钥匙	回到第 6 步确认公钥；若第 4 步用的是管理员 PowerShell，改用普通 PowerShell 重新生成一对
The authenticity of host ... can't be established	首次连接，正常的指纹确认	输入 yes 回车，只出现一次
提交后 Gitee 上不显示是我提交的	第 3 步 user.email 填错了	改成 Gitee 账号的邮箱，之后的新提交即可正常归属
Repository not found / 403	没被加为本项目协作者（本项目是私有仓库）	联系项目负责人添加协作者权限
Access token is expired	你在用 HTTPS + 令牌的方式，没走 SSH	用第 8 步的 git@ 地址重新克隆，不要用 https:// 开头的地址
ssh -T 卡住超过 30 秒	公司网络屏蔽了 22 端口	Gitee 的 SSH 只支持 22 端口，被封就只能退回”HTTPS + 私人令牌”方式，联系项目负责人处理

可选：一条”防呆”配置（推荐）

加上这条后，不管从哪复制到的链接是 https:// 还是 git@ 开头，粘进去都能用，再也不用纠结链接格式：

git config --global url."git@gitee.com:".insteadOf "https://gitee.com/"

（Windows 的 PowerShell、macOS 的终端里执行效果相同。）

安全提醒（重要）

1. id_ed25519（不带 .pub 的那个文件）是私钥，等同于你的身份证明——任何情况下都不要发给别人、不要传到网上、不要放进代码仓库
2. 只有 id_ed25519.pub（公钥）是可以对外提供的
3. 换电脑或怀疑泄露时，到 https://gitee.com/profile/sshkeys 删掉旧公钥，回到第 4 步重新生成一对即可

小结

通过本小节的学习，您已经掌握了：

技能	关键操作
SSH 免登录原理	公钥（锁）挂 Gitee、私钥（钥匙）留本机，永不过期
Windows 配置	ssh-keygen 生成 → Set-Clipboard 复制 → 网页粘贴公钥 → ssh -T 验证
macOS 配置	命令一致，复制公钥用 pbcopy，桌面路径 ~/Desktop
IDE 日常协作	克隆 → 打开文件夹 → 源代码管理面板提交推送，全程免密
防呆配置	url."git@gitee.com:".insteadOf 自动把 HTTPS 地址转成 SSH

正在开发商业 IoT 产品？

我们提供 ESP32 ODM 定制设计与制造服务。从原型到量产——编写这套教程的团队，可以和你一起实现。

联系我们 →